Writing APIs requirements: the best of API goal canvas and DDD Event Storming

Writing APIs requirements: the best of API goal canvas and DDD Event Storming

Today I would like to talk from an elevated perspective about a topic I enjoy: APIs. Because when well-designed, they help us produce highly sustainable software. But this is not an easy task...

The API goal canvas

The API goal canvas is an API modeling tool suggested by Arnaud Lauret in his excellent book "Designing Web API" at Manning. It is very simple and efficient: it involves filling in a table that lists the APIs to be executed for a user to reach his goal (eg: "Place an order").

To create an API goal canvas, you can provide the following information:

  • The "what": what does the user want to do?

  • The "who": who has access to the resource?

  • The "how": what are the necessary API steps to achieve the user's goal?

  • API inputs and outputs.

  • The goal of the API.

Other columns can be added as needed:

  • The category: purchase, administration, ...

  • The scope to manage permissions, for example buy:create, admin:manage_products...

  • The endpoint path.

  • ...

Here is what it could looks like for an online store:

The problem

The API goal canvas is a very simple and efficient tool, domain experts can quickly adopt it. However, it has some drawbacks:

  • The level of detail is important. This can be problematic in large domains: how to forget as few APIs as possible?

  • In a microservices architecture, systems need to communicate. But when? What messages to send to other systems?

To answer these questions, DDD's Event Storming is of great help.

Event storming to the rescue


Event storming is a method for discovering and modeling a business domain. It is a question of being interested in first place in the events which occur in this domain. This makes the work efficient: events are facts that happened and they are non-debatable.

The principle is as follows:

  1. Get post-its (it can be a lot!).

  2. Invite the different profiles of your team: developers, business experts, testers...

  3. Ask everyone to write on a post-it an event that happened in the domain. For example: "An order has been paid.". The participants must be at ease: there is no harm in imagining an event that does not exist in reality. The audience is here to learn from each other.

  4. Organize and sort the events in chronological order.

  5. For each event, ask participants which command (which process) is at its origin. Other information can be added on other color post-its such as aggregates.

Here is what it could look like for our online store:

Domain Events as API goal canvas milestones

We can use domain events in the API goal canvas as the milestones of our API journey. This allows a classic problem-solving approach: thoughts must begin by identifying the objectives to be achieved.

Step 1: focus on the essentials

In the previous example, the "Validate cart" API is missing in our first canvas because we dove too much into the details.

So we need to focus on the essentials first:

  • Let's remove the input and output columns. These are implementation details.

  • Add the events and their associated command.

  • Add all the actions that lead to the event.

Step 2: complete the API canvas

Now it's about identifying all APIs and their implementation details (input, outputs, scopes, ...) that lead to a consistent API journey. Pay attention to the input and output data to ensure that it will be possible to chain API calls.

Below is an example of a completed API goal canvas:

Domain events are of great interest

Domain events serve as milestones during the APIs requirement analysis. They also play a vital role in microservices architectures:

  1. They make it possible to establish clear audit trails.

  2. They allow microservices to communicate asynchronously

  3. They allow caches to update. I will talk about that in further articles.

In summary

To effectively identify the APIs to be implemented within a business domain and make them useful in your system, adopt an "Event first" (or "Message first") approach:

  1. Organize a DDD Event storming.

  2. Use the results of this work to create the milestones of your API goal canvas.

  3. Complete your API goal canvas by identifying the APIs needed to reach these milestones.

  4. Finally, add all implementation details you need (input, output, scopes, goal, ...) for your APIs into your goal canvas.

About the cover image

Messier 78. This well-known reflection nebula is found in the Orion constellation, just above Horsehead nebula. It asks very clear skies to be photographed.

View it in large size on my website.