Getting Started with Microservice API Patterns (MAP)

In a previous post, I reflected about the evolution of Microservice API Patterns (MAP) since 2016. This “meta-post” points you at presentations and articles motivating the need for MAP, introducing the language structure and featuring sample patterns.

Update (12/2022): The book is published! Read on. Its Table of Contents is available here.

Update (08/2022): Our pattern language for API and service design forms the core of a forthcoming Signature Series book to be published by Pearson in December 2022! Read more.

Update (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”.

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 endpoint 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, please find an extended version of the IEEE Software blog post here (2200 words).

This online overview 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 article and this article have all the details.

Element Stereotypes (March 2021)

Next up were representation element stereotypes such as ID Element, Link Element, 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.

Overview and Pagination (February 2022)

Eric Wilde wrote about MAP in the Axway blog: “Microservice API Patterns: A Language for API Design” (February 15, 2022).

You can always contact me if you have questions, comments or suggestions. There is a Medium version of this post.

– Olaf (in MAP Author role)