Spring I/O 2026: Crafting Great APIs with Domain-Driven Design
Just wrapped up my session Crafting Great APIs with Domain-Driven Design at Spring I/O 2026 in Barcelona! The session is based on the book I co-authored with Annegret Junker, and while she couldn’t join me on stage this time, our ideas and shared work were very much present throughout.
Abstract
Most APIs fail not because of technical shortcomings, but because they don’t reflect the business domain they’re meant to serve. We end up with generic CRUD endpoints that leak implementation details, tightly couple consumers to our internal models, and crumble when requirements evolve.
Domain-Driven Design offers a way out, but applying DDD to API design requires more than just naming conventions. It demands a collaborative methodology that bridges the gap between business stakeholders and technical implementation.
In this session, we’ll explore a practical approach to crafting APIs that truly represent your domain. Starting with Domain Stories to capture business workflows, we’ll derive a Visual Glossary that establishes a shared Ubiquitous Language. From there, we’ll use the API Product Canvas to shape APIs as products, with clear boundaries, consumer, and focus.
But great APIs aren’t just request-response. Therefore, this approach covers a streamlined way to identify and design both synchronous and asynchronous APIs.
We’ll walk through a complete design journey: from Business Model Canvas through strategic design with capability mapping and Domain Storytelling, to tactical design with Event Storming and Visual Glossary, and finally to an API specification in OpenAPI or AsyncAPI, accelerated by LLMs.
Your API Is Lying to You
The core message: too many APIs start life as YAML files, but business people don’t like YAML, and developers immediately get lost in syntax and parameter debates. That’s the real gap, and it’s where Domain-Driven Design comes in.
Our Collaborative Design Approach
We walked through our full collaborative design approach:
- Create Capabilities with the Business Process Canvas
- Map Capabilities with Wardley Mapping
- Domain Storytelling
- Event Storming
- Visual Glossary
- Context Mapping and service cut
- Define APIs and their communication pattern
- Implementation
…and iteration at all levels.
The API Product Canvas ties it all together as a short profile of a bounded context, covering both synchronous and asynchronous communication in a single approach.
From Visual Models to Working Specs
I also showed how LLMs can accelerate the last mile, feeding the API Product Canvas and Visual Glossary diagrams into Claude to generate valid OpenAPI or AsyncAPI specs. From visual models to working specifications in minutes.
Key Takeaways
- Collaboration is the key: Modeling works better visually, in cross-functional teams
- The API Product Canvas and Visual Glossary give you a concise bounded context profile
- One approach that covers both sync and async communication
A Fantastic Audience
What really made it special was the audience. Sharp questions, great energy, and conversations that kept going well after the session. That’s what makes Spring I/O such a fantastic conference.
Thank you to Sergi Almar and the entire Spring I/O team for having me!
Links & Resources
Book:
- Crafting Great APIs with Domain-Driven Design (Springer, 2025) by Fabrizio Lazzaretti & Annegret Junker
Related Talks:
