Issue #64

I’ve been discussing API design methods, and in this post I want to describe the first methodology I’ll review – Annegret Junker and Fabrizio Lazzaretti’s Synergetic Blueprint [1][2][3]. I’ll describe the phases and steps involved, to set the stage for a review, which I’ll do in a subsequent post.

The creators of the Synergetic Blueprint describe it as a method to go from a business idea to team-owned bounded contexts with APIs between them. Thus, the Synergetic Blueprint leans heavily on Domain-Driven Design (DDD)[4]. The steps involved are:

I would say that the Phase I and Phase II are traditional DDD phases. They serve as a foundation for Step 7, which is at the heart of the Synergetic Blueprint API design method – creating a high-level API design with an API Product Canvas. As you will see later, API descriptions (whether for synchronous APIs using OpenAPI or asynchronous APIs using AsyncAPI) can be generated from the API Product Canvas using AI. 

Here is a simplified schematic of the Synergetic process

Before continuing, I want to say that my primary source for describing the Synergetic Blueprint is  Annegret Junker and Fabrizio Lazzaretti’s book, “Crafting Great APIs with Domain-Driven Design”[1]. But I have also added to my understanding of it using the authors conference presentations[2] and articles[3]. Where I have noticed slight discrepancies in how the process is described in these sources, I have interpreted the process as I have understood it.

Now let’s look at these steps in more detail. 

This phase involves business modelling. Step 1, 2 and 3 involve a series of workshops where “business people and technology nerds discuss and sketch ideas more as a game than a serious activity.”[1] Business people and technologists work to understand the business model using a Business Model Canvas, the core capabilities of the business using a Capability Map, and prioritising the capabilities using Wardley Mapping (which also has a canvas for that). The Wardley Map helps the team understand if an identified capability is a differentiator (so requires custom investment) or a commodity (so can be bought off-the-shelf or reused). Product leaders and Enterprise Architects are heavily involved at this stage. According to Annegret and Fabrizio, “Such a workshop can result in the creation of stakeholders’ commitment and a shared understanding of the business idea. The workshop result is a Business Model Canvas and the first ideas of business capabilities.”[1]

Phase outputs: First sketches of ideas (like user interface designs and workflows), Business Model Canvas, a Capability Map (that defines what the business can do) and Wardley Map. 

A table summarising Phase I of the Synergetic Blueprint is shown below.

This phase is about discovering the Bounded Contexts and is at the heart of DDD. 

This step involves using Domain Storytelling to create a Visual Glossary. In Domain Storytelling, domain experts and engineers collaborate to visually capture how work gets done in the business domain, by ’telling stories’ of real world scenarios. The business requirements are captured as Domain Stories in a visual diagram showing actors, actions they do, key business objects and sequences - the Visual Glossary.

Step output: 
1. Domain stories captured visual diagrams 
2. Visual Glossary. 

To further understand the business process, teams can run an Event Storming workshop to collaboratively model the business domain and map Domain Events that happen over time. This helps teams uncover the real business process and bounded contexts and capture them in a Context Map.

Step outputs:

This step is done towards the end of the Event Storming workshop. The team creates a Context Map that shows how the different Bounded Contexts relate to each other. The relationships shown in the Context Map provides the basis for defining APIs and communication patterns that connect them. A Bounded Context Canvas can be used to document the context.  

Step outputs:
1. Context Map  

To wrap up Phase II, here is a table summarising the inputs and outputs of the phase.

Having laid the DDD foundation, the authors come to the software solution design, including the actual API design work. This phase involves combining the domain stories, context maps, and other artifacts created in the Phase II, to create a solution design documented in a Bounded Context Canvas, Architecture Communication Canvas, and Architecture Decision Record. But the design also includes a high-level definition of the APIs using an API Product Canvas. From this canvas, a detailed design API description (OpenAPI or AsyncAPI) can be generated using a GenAI tool. Again the authors recommend doing the tactical design in a workshop format to foster collaboration between product / business experts and technology teams. 

Because I am focusing on API design methodology, for brevity I will ignore all the other artifacts in and focus on the API Product Canvas, and generated API descriptions.

To support the high-level design of synchronous and asynchronous APIs, the authors created an API product canvas. The canvas has several sections to fill, but some to call out are 

It also includes sections for defining the data to be received in requests and returned in responses. You can find a template for the API Product Canvas on Miro.

An example of the canvas, taken from one of the authors’ conference presentations [5] is shown below:

Having created this high-level design of the API, the authors recommend using AI tools to generate an API description file from it. The completed API Product Canvas and the Visual Glossary can be used for this. Here is an example prompt the authors provide [3] for creating an OpenAPI file:

Step outputs:
1. API Product Canvas
2. API description file (OpenAPI, AsyncAPI etc)
3. Bounded Context Canvas
4. Architecture Decision Records
5. Architecture Communication Canvas

To wrap up Phase III, here is a table summarising the inputs and outputs of phase.

The above seven steps conclude the Synergetic Blueprint method. But the authors also mention that an API design is not static - there can be a need for feature extensions and enhancements. 

When making design changes to an existing API, Annegret and Fabrizio mention Domain Storytelling and EventStorming as workshops to rerun to flesh out the requirements for API changes. 

As you have seen, the Synergetic Blueprint is a method that helps an organisation go from a business idea to well defined bounded contexts exposed via APIs. It is a domain-driven, architectural design method in which one of the outputs is an API description file. The overview of the Synergetic Blueprint described in this post sets the stage for the next part of my series – a review of the process. In my next article, I will do an opinionated review of the Synergetic Blueprint from my perspective.

[1] A. Junker and F. Lazzaretti, Crafting Great APIs with Domain-Driven Design: Collaborative Craftsmanship of Asynchronous and Synchronous APIs, 1st ed. Berkeley, CA, USA: Apress, 2025.

[2] F. Lazzaretti, “From AI to API,” devmio, 2026. [Online]. Available: https://devm.io/api/from-ai-to-api

[3] F. Lazzaretti and A. Junker, How to Design OpenAPIs in Workshops: The API Product Canvas, presented at apidays Munich 2025, Munich, Germany, July 2–3, 2025. [Online]. Available: https://lazzaretti.me/talk/2025/ApidaysMunich-API-Product-Canvas-OpenApi.pdf

[4] A. Junker, Mastering Domain-Driven Design: Collaborative Modeling with Domain Storytelling, Event Storming, and Context Mapping. New Delhi, India: BPB Publications, 2025.

[5] F. Lazzaretti and A. Junker, How to Design AsyncAPIs in Workshops: The API Product Canvas, presented at apidays London 2025, London, U.K., Sept. 22–24, 2025. [Online]. Available: https://lazzaretti.me/post/talks/2025/apidays-london-api-product-canvas/ApidaysLondon2025-API-Product-Canvas-AscynApi.pdf

How to generate a TypeScript SDK from your OpenAPI spec: CJ Avilla argues that while basic open-source generators are suitable for internal prototypes, production-grade public SDKs require "idiomatic" features such as automatic retries, built-in pagination, and sophisticated error handling.

How to Implement Geolocation Routing on Your API: Martyn Davies provides a technical guide on implementing geolocation routing to address the increasing demands of data residency, compliance, and global performance.

What Comes After Ingress NGINX? A Migration Guide to Gateway API: Michael Levan outlines the strategic shift from the ubiquitous but ageing Ingress NGINX controller to the modern Kubernetes Gateway API.

How to Choose the Right Load Balancing Strategy for Your Use Case: Simon Delicata offers a strategic framework for selecting load-balancing algorithms based on specific infrastructure needs rather than general defaults.

What is Semantic Caching?: Matt Tanner explores the evolution of caching mechanisms specifically tailored for the era of Large Language Models (LLMs).

Agent skills for OpenAPI and SDK generation: Vishal Gowda from Speakeasy introduces "agent skills," a collection of specialised capabilities designed to empower AI coding assistants in managing the API lifecycle.

Why It’s Good to Be API-First in the AI Era: Kristopher Sandoval asserts that the "API-first" philosophy has gained renewed significance as the primary enabler of AI-driven automation.

Are Your APIs Ready for AI? Preparing Your Landscape for Intelligent Consumption Eric Wilde explores why traditional API management strategies may be insufficient for the era of "intelligent consumption" by LLMs and AI agents.

API standards: foundational for agentic AI: Bill Doerrfeld, Kin Lane, Lorna Mitchell and Kevin Swiber explore the indispensable role of established API standards in the burgeoning era of agentic AI and autonomous tool calling. Full video here.

Stainless CLI generator: The Stainless Team introduces their automated Command Line Interface (CLI) generator, designed to transform any OpenAPI specification into a fully functional, type-safe terminal tool.

If you find this newsletter valuable, please share and forward it to your network.

KubeCon + CloudNativeCon: The Cloud Native Computing Foundation’s flagship conference. Amsterdam, Netherlands from 23-26 March, 2026.

Apidays New York: Location: Convene 360 Madison, New York, Date: 13 - 14 May 2026

API Conference London 2026: The Conference for Web APIs, API Design and Management Date: May 11 – 15, 2026, Location: Park Plaza Victoria London, UK.

Nordic APIs Platform Summit 2026: October 12 – 14, 2026, Location: Stockholm, Sweden