Getting APIs to Work: Crafting Great APIs with Domain-Driven Design
I had a great conversation with Erik Wilde on his Getting APIs to Work podcast about Crafting Great APIs with Domain-Driven Design: Building APIs That Last. The episode digs into the ideas behind the book I co-authored with Annegret Junker: why so many integration efforts stumble, and how a more deliberate, domain-first approach helps teams build APIs that survive change.
Better APIs in the Age of AI
Erik opened with a point I fully agree with: in the age of AI we have to think even harder about better APIs, because a good API is good for everyone, and especially for AI. The argument runs through to the end of the conversation. If an API is self-descriptive, you can hand it to an AI agent and it can use it without calling a developer to ask what a cryptic field name means or why there are four endpoints that seem to do the same thing. The same investment that makes an API understandable for humans is what makes it usable for agents. Today the friction is often a mismatch between very technical APIs and the business-focused goals an agent is given, and well-designed APIs close that gap.
From Business Problem to Long-Lived APIs
We walked through the journey the book describes, starting with strategic design and ending with APIs that last:
- Business Model Canvas to find the capabilities: where the business wants to go, who the customers are, what to focus on
- Wardley Mapping to categorize those capabilities: what is user-visible, what is a differentiator worth building yourself, and what you can simply buy
- Domain Storytelling in a workshop format so business and IT align on what actually happens in the domain
- Event Storming to capture the business events and the objects and aggregates involved, which naturally surface the bounded contexts
- API design for the interactions between those bounded contexts, looking at where events fit and where synchronous calls are needed, across REST, RPC, and GraphQL
The Visual Glossary
If you take one thing out of the book, take the Visual Glossary. It is a simple tool for capturing the important words in your domain and how they relate visually: how a book relates to a book copy, a library, or a license. Once a team agrees that a word means exactly one thing, and that becomes a published language between teams, everyone knows what is meant when it shows up in an API.
The API Product Canvas
The one genuinely new piece we added is the API Product Canvas: a single view of one bounded context with its integrations, endpoints, and events. It turned out to be a simple way to communicate to business how a technical component interacts with others, so the API can be designed together with business and not just IT. From there you can generate a first cut of the API with AI and refine it, but only after everyone shares the same picture.
Strategic, Not Just Cheap Now
We also talked about the trade-off in where the effort goes. For a quick proof of concept, just start coding, you will be faster, and Domain-Driven Design will not make that faster. But for a product that lives for years, designing the API first pays off: integration is usually the costly part of a big project, and getting the API wrong shows up as failed integrations, rework in the test phase, and errors in operation, and it makes later replacement far more expensive. APIs are forever, the code behind them will change.
Key Takeaways
- Better APIs are better for AI too: a self-descriptive API can be consumed by an agent without a human in the loop.
- Collaboration is the key: design the domain visually, with business and IT in the same room.
- APIs are forever, code will change: invest in design up front for APIs that are meant to last.
- The Visual Glossary and API Product Canvas keep every team on the same language, across synchronous and asynchronous communication.
Links & Resources
Book:
- Crafting Great APIs with Domain-Driven Design (Springer, 2025) by Annegret Junker & Fabrizio Lazzaretti
Connect:
Related Talks:
