Principles of Web API Design Chapter 5

Identifying API Boundaries

This is a continued blog post series you can find the first post here.

Chapter 5 starts out mentioning the strong inspiration this book draws from Domain Driven Design (DDD). In the resumé of previous chapter we touched on event storming as a tool to identify Bounded Context’s. The Bounded Context pattern is one of the most use full strategic DDD patterns.

An API needs to have a clear purpose and be clear on what business capability it offers to the user. The Bounded Context Pattern is an obvious tool to use solving this problem.

But before going into details some Anti patterns are highlighted:

The Mega All-in-one API Antipattern

One huge API will make it difficult for developers to find what the API does exactly and if their need are covered. They might have to browse the whole API to determine that.

This of cause leads to the problem: How do we then split the API? And here the suggested analysis method is the collaboration tool Event Storming which helps us identifying DDD bounded Contexts.

The Overloaded API Antipattern

This antipattern is closely related to the Mega API Antipattern. Its not difficult to imagine an API being expanded over time when lots of new ideas arise. The Danger is an unfocused API that does everything, but nothing is done well. Again the illusion that we can have one unified model of our business gets exposed by sound DDD practice. We should not have one big model but multiple smaller models according to bounded contexts.

The Helper API Antipattern

This is a typical one 😉 A development department wants to avoid code duplication. They start out having a shared helper library, that gets expanded by time. That library gets promoted to being an API, which could solve other problems of keeping dependencies in sync. But more and more gets added to the helper API, and it becomes unfocused and unstable since there will be a need for constant updates, because the helper API solves to many uncoherent problems.

The Event Storming Canvas

From a design level event storming we have repeated sequences of

commands, aggregates and events; with read model, policy and user interface springled in here and there.

These are transferred to an Event Storming Canvas.

Aggregates can be used as hints to defining different API’s around these aggregates. But IMPORTANT: This can be to fine grained. Remember that the API is not the same as a domain model. So some details might no be right to expose in the API.

But in this example it is actually the case. So rather than one single API we see 3 smaller API’s emerge. Each centered around an Aggregate.

The dark green sticky notes represent API Candidates.

Using Activities to identify API boundaries

It also gets mentioned that you can use the activities identified in previous chapters to find the API boundaries. Here You can listen for changes in language. If the language for business concepts changes, then it’s a sign that a boundary exist here that we should follow.

Summary

The artifacts we had from previous step in the ADDR process is a design level event storm. and activities and steps for digital capabilities. This chapter brings us forward in the process by identifying concrete API boundaries very close to a DDD bounded context. One concrete exercise is using an event storming canvas.

I noticed several things that I would like to highlight.

It’s clear that the API is more than just a data contract. In the given example it becomes clear that the API is also a process or a conversation like James has highlighted previously.
The concept of a Slice in Event Modelling is very similar to each row in an event storming canvas.
This is a good example of how Domain Driven Design can be used in practice. Many organizations, teams and individuals struggle with how exactly do we get from DDD analysis to practical use.
In the Event Storming Canvas: Why do we highlight the User and not the trigger from Job To Be Done (JTBD) stories. The whole point was to replace mentioning the user role with the more useful trigger, like in when is it the user would consider using a digital capability to achieve an outcome?
- I Asked James about it and he pointed me to the fact that the book actually goes into this. While using a trigger is a preferred way of framing the job stories, reality sometimes kicks in and focusing on the user role is necessary. One example is related to access rights. A user with specific access rights to certain capabilities makes it advantageous to specifically mention the user role in the job story and therefore also in the event storming canvas.
A useful tip in relation to identifying API Boundaries with event storming is to look for the so called pivotal events. This will typically overlap with the tip of looking for changes in language. A pivotal event is an event that during event storming typically gets marked with yellow tape placed vertically like shown here.

A pivotal event is often an event indicating an end of a sub process or a transition from one system to another. This often coincide with a change in language as well. Paying careful attention to language is a Principal Domain Driven Design advise by the way.

Read more about pivotal events at virtualDDD