Article Series 'API Design Pattern of the Week'

The authors of the Addison-Wesley book “Patterns for API Design — Simplifying Integration with Loosely Coupled Message Exchanges” publish(ed) 21 articles online last year, featuring selected patterns from their book. The series started as LinkedIn articles (14 editions) and then moved over to Medium (7 editions).

Interesting discussions took place online, including feedback up to a new pattern adoption story (in two domains, energy and e-government) from a readers group in The Netherlands. This post gives an overview of the series and reports some discussion highlights.

The Article Series by Pattern Category

The API design pattern language has five categories, corresponding to book chapters:

Let’s walk through these categories now.

Foundation patterns deal with API visibility and supported type of integration. The ones featured in the series are:

• Public API is one of three visibility options.
• API Description is a generalization of service contracts, OpenAPI specifications, and so on.

There are four more foundation patterns, including Frontend Integration and Backend Integration. The other visibility options are Community API and Solution-Internal API (for instance, to connect microservices).

Responsibility patterns are architectural in nature. The patterns in this category clarify the technical roles of API endpoints and the semantic responsibilities of their operations. The patterns from this category featured in the article series are:

• Processing Resource, modeling activity-oriented API endpoints in the pattern language.
• Information Holder Resource, representing data-oriented API endpoints.
• Data Transfer Resource makes the Web asynchronous because it decouples two applications that want to exchange data by turning them into two API clients of the same API endpoint (the Data Transfer Resource, that is).
• State Transition Operations update Information Holder Resources or advance provider-side Processing Resources from activity to activity.
• Retrieval Operation represents read-only get operations.

There are six more responsibility patterns in the book and on the website, representing special-purpose information holders, create operations that initialize state, and stateless computation functions.

Structure patterns, well, deal with (message) structure. Five category members are featured in the series:

• Id Element for payload parts that help identify and distinguish anything that needs to be identified and distinguished (data elements, API endpoints, and so on).
• Metadata Element is one of the less obvious patterns, but very common in enterprise application integration. Metadata is data about data.
• API Key is a common pattern, often seen under this very name.
• Error Report bringing error codes and messages into the message payload.
• Context Representation is an advanced pattern grouping processing metadata of various kinds.

Six more patterns dealing with message structure can be found on the website and in the book (see category overview page on the patterns website).

Quality patterns. An API provider has to compromise between providing a high-quality service in a cost-effective way, and to communicate related design decisions. The patterns from this category that are featured in the series are:

• Embedded Entity is one of two patterns directly addressing the API endpoint and message granularity topic.
• Linked Information Holder is the other one. This is the only pattern name I am not 100% happy with in hindsight. I’d rather call it Information Holder Link now.
• Wish List turns the API provider into Santa Claus; clients may select data they are interested in. 😉
• Pagination has a lot of interesting forces and is harder to implement efficiently than one might think.
• Conditional Request is well-known from HTTP (caching).
• Rate Limit is one of the patterns providing quality management and governance.
• Service Level Agreement complements API Descriptions with specific and measurable quality goals that are monitored at runtime. Most known uses listed on the website deal with availability (aka uptime); the arc42 Quality Model provides examples for many desired qualities and ways to quantify them, including efficiency (incl. reponse time and throughout). The arc42 model can serve as SLA/SLO input.

Three more quality patterns are available online and in the book (note that there is some overlap between structure and quality). InformIT has an article on them as well: “How to Shape Responses to API Calls”.

Finally, the evolution patterns category deals with lifecycle management concerns such as versioning and release/decommissioning strategies. Two evolution patterns are part of the series:

• Version Identifier, to be placed in endpoint addresses (such as URIs in HTTP resource APIs), protocol headers, or payload.
• Two in Production sparked an interesting discussion, concluding with the advice to only use the pattern if that is really needed — which often is the case, depending on the nature of the changes.

Five more evolution patterns wait for you on the patterns website and in the book, including Limited Lifetime Guarantee and Experimental Preview.

Book/Language Organization

Patterns from the five categories can be applied on different levels of an API, as the following figure shows:

There are 21 series members in total, and 23 more “Patterns for API Design” are available on the public website and in the book. The book also has a chapter on “Documenting APIs” and their contracts, which features some of the quality patterns as well as API Description (a foundation pattern); see Chapter 4 of the book for an explanation of this publishing decision.

By the way, do not let the size of the book scare you… you do not have to read cover to cover! Part 2 serves as a reference primarily, with patterns to be looked up when its problem appears in practice (and you remember where to look 😉).

Related Projects and Books

If you are not designing greenfield APIs but improving existing ones, our emerging Interface Refactoring Catalog is for you:

Check out Introduce Pagination, Split Operation or Introduce Version Mediator to get an impression of the different types of API refactorings contained in the catalog.

We are proud members of the Vaughn Vernon Signature Series at Addison-Wesley Professional. Six books are now available, “Serverless as a Game Changer” was the latest addition at the time of writing. “Balancing Coupling in Software Design: Successful Software Architecture in General and Distributed Systems” seems to be up next. See this post for more information about the series and its authors (presentations).

Wrap up

Did this post whet your appetite for API design patterns?

• If not, you probably would not have made it here. 😉
• If in doubt, you might want to check out this post for more information about the patterns and the book. And the free online content on api-patterns.org includes extended pattern summaries, tutorials, pointers to articles, presentations and podcasts.
• If yes: try the Cheat Sheet to get started and/or when returning to our patterns. The index figure in Chapter 4 of the book, also featured on page 3 of the InformIt article“What is the Right Service Granularity in APIs?”, also provides language orientation.

Happy pattern reading and referencing! Feedback is still appreciated, as patterns are never 100% (unlike printed books). 😄

– Olaf (in role of co-author of “Patterns for API Design”)

PS: This post is also available on Medium. Another Medium story for API Design Patterns of the week listed in chronological order (not order of application). It is merely an index by week.