Microservice API Patterns: A Language for API Design

In the overall API lifecycle, it is important to first align APIs with business capabilities, turn this into a clear and business-aligned value proposition for the API, and to also produce some API stories that demonstrate how to use that new digital building block.

Moving on from this value focus, the next step then is to take the API stories and turn them into high-level designs. The result of this are “API conversations” where it is shown how an API consumer interacts with the API. These conversations are not yet specified down to the level of which protocol to use and what the technical details of the exchanged messages look like, but they do show conversation patterns.

Design Patterns

In software engineering, “a software design pattern is a general, reusable solution to a commonly occurring problem within a given context in software design”. We can look at API design as one part of software engineering: It is not concerned with how a capability is implemented, but it is concerned with making sure that consumers of the capability will have what is often called a good Developer Experience (DX). Using design patterns for APIs can give us two important benefits:

• Focus on Domain Design. By using design patterns for known aspects of API design, teams can rely on these patterns instead of having to come up with their own solutions. This allows them to focus on the domain design aspects of the problem, instead of having to solve problems for which there is a known pattern.
• Coherent API Landscape. By using design patterns across an API landscape, greater design coherence across the API landscape can be achieved. If the same pattern is used across the landscape, APIs will have a more familiar look and feel to developers that work with a variety of APIs in that landscape.

In short, API design patterns are a good idea, and to some extent they are often covered, at least a little bit, in API guidelines. But more often than not, existing guidelines do not provide many patterns, and oftentimes they are also focusing on other aspects of the API design.

This means that having and using API design patterns is a good idea, but is not practiced as much today as it could be and probably should be.

Microservice API Patterns (MAP)

Microservice API Patterns (MAP) is a collection of practices during the API design process that can help to more quickly come up with an API design that is a good solution for the given problem. These patterns are organized into various categories as shown in the following illustration.

As an illustration of how patterns work, let’s look at one specific pattern. Within the “Structure” category, there is a pattern called “Pagination”. This pattern is useful in cases where, as part of the API conversation, larger item sets are used, and as a result it makes sense to design interactions so that these results are provided in a paginated way.

When describing the pattern, it starts with a context which addresses the problem in general and also discusses additional constraints. For example, for pagination it makes a big difference whether the result set is supposed to be stable (in which case it needs to be stored by the server for a certain time), or whether it is treated as a dynamic view that can change in between requests for various pages.

The problem then simply states the problem that is addressed by the pattern. In this case, the problem is: “How can an API provider deliver large sequences of structured data without overwhelming clients?”

Forces then discuss the various forces that influence a solution and how desirable it is. This section is a good way to shape the discussion and decision around which solution to choose.

The solution then discusses the general idea of the pattern, which in this case is to provide an API that supports pagination.

Finally, the pattern also discusses known uses which makes it easier for designers to look at APIs that are using this pattern. There may also be standards supporting this pattern, in which case they would be listed under here as well.

Conclusions

Microservice API Patterns (MAP) are a good way to think about how to address some of the design decisions that need to be made as part of the API design process. The site lists a substantial number of patterns and is interesting to check out both for API beginners as well as for more experienced API practitioners.

If you’re interested in more detailed information, please check out the following video with Daniel Lübke, one of the creators of MAP (the others are Olaf Zimmermann, Mirko Stocker, Uwe Zdun, and Cesare Pautasso). He discusses the motivation for MAP, the general goals and organization into categories, as well as one example pattern.