Skip to content
Software Architecture Guide

Patterns for API Design

Explanation

Section titled “Explanation”

A pattern language is a set of related patterns that work together. This one covers the design of remote APIs. Its online home is the Microservice API Patterns (MAP) site. MAP focuses on message representations, meaning the payloads exchanged when a client calls an API. The structures you choose for these messages strongly shape the API’s qualities, both at design time and at runtime.

How the book is organized

The book has two parts. The first covers fundamentals: a domain model and a decision model. The second presents 44 patterns in Chapters 4 to 9, grouped into five theme categories. Thirty of the 44 patterns were peer-reviewed and published in papers before the book appeared.

The decision model treats patterns as architectural decisions (see Architectural Decision). Each decision is a pattern selection question with options and criteria. The book’s decision narratives identify 29 recurring decisions. The author’s page numbers this as Chapter 2. The publisher’s table of contents puts it in Chapter 3.

The five categories

  • Foundation: the first category of the language.
  • Responsibility: defines endpoint roles. Processing Resource lets clients trigger an action in the provider. Information Holder Resource exposes domain data and hides how it is implemented.
  • Structure: covers message structure. Parameter Tree expresses containment. Id Element tells API elements apart at design time and at runtime.
  • Quality: includes Pagination, which delivers large data sequences without overwhelming clients. Rate Limit stops clients from using the API excessively. Wish List is also in this category.
  • Evolution: includes Limited Lifetime Guarantee, which tells clients how long they can rely on a published API version.

Example

Section titled “Example”

A team builds an API for an online shop. They give the order list the role of an Information Holder Resource, because it exposes data. They give “cancel order” the role of a Processing Resource, because it triggers an action. Next they ask the quality questions. Should the order list use Pagination? Should the API apply a Rate Limit? Last, they ask an evolution question: how long will version 1 stay available? They write each answer down as a decision with its options and reasons.

Trade-offs

Section titled “Trade-offs”

The facts here describe the structure of the language, not its costs. One point is worth noting. Message structure choices affect both design-time and runtime qualities, so a choice that helps one quality may affect another. Weigh each decision against its criteria and record the result.

The five categories of the pattern language, with example patterns.

Diagram source 
mindmap
  root((API design patterns))
    Foundation
    Responsibility
      Processing Resource
      Information Holder Resource
    Structure
      Parameter Tree
      Id Element
    Quality
      Pagination
      Rate Limit
      Wish List
    Evolution
      Limited Lifetime Guarantee

Checks

Section titled “Checks”
  • API design choices, such as pagination or rate limiting, are recorded as decisions with options and criteria.
  • Each API endpoint has a stated role, for example Processing Resource or Information Holder Resource.
  • The document states how long clients can rely on a published API version.
Section titled “Related”

Sources

Section titled “Sources”