Part 2
The Patterns
This part of the book presents our catalog of patterns for API design and evolution. Complementary to Chapter 3, “API Decision Narratives,” in Part 1, it does not have to be read page by page but serves as a reference.
The catalog is organized along the four phases of the Align-Define-Design-Refine (ADDR) process introduced in Principles of Web API Design: Delivering Value with APIs and Microservices [Higginbotham 2021]:
In the early stages, the API scope is derived from and aligned with client goals and other requirements, as, for instance, articulated in user stories or job stories. We briefly summarize the related foundation patterns that are eligible in this phase.
Still at an early stage of the API design, endpoints and their operations are defined on a rather high level of abstraction and elaboration. Our responsibility patterns come into play in this phase.
Next, technical details and technology bindings are designed. This is where our message structure and API quality patterns have their place.
Finally, the API designs and their implementations are continuously refined during API evolution. Additional quality patterns can also be applied in this step, often in the form of API refactoring (to patterns).
The progress with the API design is continuously (and incrementally) documented throughout the design and evolution steps. Appendix A, “Endpoint Identification and Pattern Selection Guides” explains how the four ADDR phases and its seven steps (for instance, “Model API profiles”) and our patterns relate to each other.
The chapter structure of this part comes from these considerations. Each chapter targets at least one role in our target audience:
Chapter 4, “Pattern Language Introduction,” provides a pattern language overview and introduces foundation and basic structure patterns that serve as building blocks of the patterns in the subsequent chapters.
Chapter 5, “Define Endpoint Types and Operations,” discusses endpoint roles and operation responsibilities, taking a conceptual architecture view on API design and evolution.
Chapter 6, “Design Request and Response Message Representations,” is about request and response message structures, targeting integration architects and developers.
Chapter 7, “Refine Message Design for Quality,” presents patterns that improve message structures with respect to certain qualities. This chapter also targets architects and developers.
Chapter 8, “Evolve APIs,” discusses API evolution and life-cycle management. The API product manager comes in as an additional targeted role.
Chapter 9, “Document and Communicate API Contracts,” covers API documentation and commercial aspects. It is relevant for all roles, API product managers in particular.
Let’s get started with the pattern overview and orientation.