Getting Started with API Design Patterns
A Language for API Design and Evolution
This short story motivates the need for API design patterns and points you at resources that introduce our language and feature selected patterns.
News (08/2022): Our pattern language will form the core of an upcoming book called “Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges”, announced by the Addison Wesley Signature series editor Vaughn Vernon on Twitter and LinkedIn on July 24. Learn more.
News (02/2022): Watch my co-author Daniel Lübke explain the why and how of MAP in a 24-minute video interview in Erik Wilde’s “Getting APIs to Work”. And Eric Wilde wrote about MAP in the Axway blog: “Microservice API Patterns: A Language for API Design” (February 15, 2022).
TL;DR: Patterns for Message Representations in API Design
MAP starts where the seminal Enterprise Integration Patterns (EIP) book stops. It investigates the structures of the EIP Document Message, Command Message and Event Message payloads that are exchanged between API clients and API providers (for instance, when HTTP GET, POST and PUT operations are processed, but also when JSON or XML documents travel across queue-based messaging systems):
Presentations
An overview presentation on MAP (and Context Mapper) is this one. More slides can be found here.
IEEE Software Blog Post (April 2019)
This is a 1300-word overview of MAP. It discusses what makes service design hard (and interesting), and then introduces quality patterns such as API Key, Wish List, and Rate Limit.
MAP Overview on Website (April 2019)
If you can take a little more time, please find an extended version of the IEEE Software blog post here (2200 words).
The online article contains a definition of microservices and identifies a number of concrete design questions (answered by the patterns in MAP and related languages). It also suggests several entry points into the language, including a Cheat Sheet.
Conference Paper (January 2020)
The conference post-proceedings paper accompanying my Microservices 2019 keynote features an extended version of the online overview and the two patterns Embedded Entity and Linked Information Holder that answer the question from the scoping figure above (“Embed nested entity data? Link to separate resource?”). (5900 words)
Responsibility Patterns (October 2020)
Four MAP categories went through the EuroPLoP shepherding and writers’ workshop process and are available on the website; the Responsibility Patterns are the latest addition to this collection of peer-reviewed and published API design patterns. They apply Responsibility-Driven Design to the API domain to clarify the architectural role of endpoints and the read-write semantics of operations.
Here are two examples. The endpoint-level pattern Data Transfer Resource lets two or more applications exchange data in a loosely coupled fashion (via API calls), and the operation responsibility State Transition Operation describes update semantics (from simple actions to entire business process flows). This and this article have all the details.
Element Stereotypes (March 2021)
Next up were representation element stereotypes such as ID Element, Link Element, and Metadata Element.
These element stereotypes are also featured as decorators in the Microservice Domain Specific Language (MDSL).
Context Representation, Foundation Patterns, Pagination 2.0 (June-September 2021)
Check out the MAP news page for these and other updates. You can always contact me if you have questions, comments or suggestions.
Olaf (a.k.a. Doc Soc)
Originally published at https://ozimmer.ch on May 6, 2020.
© Olaf Zimmermann, 2020–2022. All rights reserved.
