Patterns for API Design: Adoption Story Part 3

This article presents our third Patterns for API Design Adoption Story, featuring feedback and review comments on the 21 selected patterns published in the LinkedIn article series ‘API Design Pattern of the Week.’ This LinkedIn series was launched by Olaf and Mirko in February 2023, and an engaged readership from the Dutch Energy Sector has actively been following this this series. The challenge we undertook is applying the patterns from the book in our industry to design reliable, well-performing and secure APIs, while making design decisions and identifying trade-offs. This effort resulted in two previously published adoption stories: Story 1 was released on March 26, 2023, and Adoption Story 2 on August 26, 2023. With exactly a 5-month time span between the adoption stories, this Adoption Story 3 is published on January 26, 2024 (applying a managed and predictable story version policy pattern 😉).

“Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges” is co-authored by: Olaf Zimmermann, Mirko Stocker, Daniel Luebke, Uwe Zdun and Cesare Pautasso. It was published in November 2022. It serves as the Swiss army knife for software engineers and architects in designing, evolving, and documenting APIs. We find this book excellent and are inspired and convinced that we can derive significant benefits from its architectural knowledge and patterns.

A pattern a week

At the time of this writing, 21 patterns have been published in the weekly design pattern series on LinkedIn, leaving 23 more patterns to go. See the overview of reviewed patterns below:

Weekly featured patterns per theme category

The three adoption stories each involve 7 design patterns. In this adoption story (part 3), you will find the 7 most recently published patterns from the LinkedIn miniseries listed below, along with a feedback fragment:

Rate Limit: this pattern is commonly used in Dutch government APIs, particularly in open data government services. Rate limits are a standard practice for these types of APIs and are technically implemented. However, client awareness and (how much of the rate limit is used?) is sometimes poorly managed…..;
Context Representation: this pattern is al less obvious one. Typically, context information such as authentication and authorization, is frequently managed by API gateway intermediaries using standardized and generic methods. The book rightly emphasizes that advocating for protocol independence, this pattern offers an alternative approach to relying solely on standard headers and the header extension capabilities of the networking protocol…..;
Service Level Agreement: SLAs are frequently incorporated into the terms and conditions of services, as denoted in the API Description itself (under ‘termsOfService’ and contact details) within Dutch Government APIs. As legally binding documents, terms and conditions, along with Service Level Agreements for public APIs, are drafted, or at least reviewed and approved, by legal experts specializing in the field…..;
Version Identifier: Versioning is a hotly debated topic in the API community and the book states correctly that the version strategies differ widely and are debated passionately. There are many questions and discussions floating around the internet about the correct way you should version your API’s. However, in many cases, people tend to fixate blindly on the versioning issue. But the fact that there are so many perspectives on the topic of versioning probably indicates that there isn’t a single universal solution for this issue – there is no single ‘right way’…..;
Retrieval Operation: This is a very common pattern and is described in detail and elaborated upon in the book. Next to GraphQL, OData is a query-based API protocol that is standardized and managed by OASIS…..;
Public API: Obviously, there are many Public APIs offered in the Dutch Dutch Government Public sector and they are available and discoverable via public developer portals…..;
Two in Production: This pattern is actively employed in the API lifecycle management strategy of the Dutch government. It is interesting to mention that in the DSO API Strategy initially, the support was limited to a maximum of three versions of an API (‘three in production’), comprising two major versions and one minor one…..;

My esteemed colleague Ruben Haasjes and I have studied and reviewed these 7 latest design patterns. We also assessed the extent to which we are currently applying or planning to apply these patterns in the energy sector. The result of this investigation includes review comments covering ‘Known Uses’ and ‘Discussion Input,’ integrated into previous adoption stories and fully available at:

https://api-patterns.org/book/pattern-adoption-story-1

Pattern filters and categories

As depicted in the theme category overview above, the patterns are grouped into five categories: Foundation, Responsibility, Structure, Quality and Evolution. Each category tackles various interconnected design considerations by addressing multiple related topical questions. The individual patterns can be organized and grouped in different ways:

By elaboration phase and iteration type: from inception to go live transition – https://api-patterns.org/patterns/byphase;
By role (from client developer to API product owner) – https://api-patterns.org/patterns/byrole;
By ADDR phase or order in which the patterns should be applied and how they relate to each other: https://api-patterns.org/cheatsheet;

Each of these resulting categories delves into a cluster of related design considerations. The book calls us, designers, to action:

… think about an API design issue you recently faced. Does it fit into any of the preceding categories? Do any of the questions and pattern names suggest that the pattern might be able to resolve the issue?

The API patterns cheatsheet is a great guide in addressing and solving design issues.

Domain-Driven Design (DDD)

source: https://contextmapper.org/docs/language-model/

Patterns for API Design encourages a DDD approach to API design. Embracing the DDD approach in API design allows us to uphold key software design principles, including modularity, encapsulation, loose coupling, and high cohesion. DDD concepts as Bounded Contexts and Aggregates can help us in definging clear boundaries and roles and responsibilities of APIs and API endpoint candidates. The Bounded Context’s Ubiquitous Language can help us in defining the terminology used for meaningful API operations and resources – after all, naming things in software is hard! On the domain model side, the book emphasizes:

… we aim for a rich and deep domain model instead of an “anemic domain model” [Fowler 2003]; this model should be reflected, but not necessarily mirrored in the API design

API modeling is not data-centric; instead, it is meant to include attributes and operations (behavior).

It’s interesting to observe the patterns in the relationship between APIs and domain-driven design (API-to-DDD mapping patterns). A few mappings for consideration that we recognize in our sector:

in identifying boundaries, first, analyze Bounded Contexts, then consider Aggregates, with Aggregate roots being good candidates for API endpoints;
based on the nature of an Aggregate, a Processing Resource is frequently favored over an Information Holder Resource;
the Aggregate and Entity patterns commonly manifest process-like characteristics, given their representation of groups of domain concepts with identity and a life cycle at runtime. Consequently, these patterns play a crucial role in recognizing candidates for State Creation Operations and State Transition Operations during endpoint identification;
Data Element: this pattern can contain instances of the “Value Object” pattern in DDD in transit; DDD “Entity” is represented as a variant of this pattern;

and more API-to-DDD mapping patterns in the book!

Note that a one-to-one correspondence between instances of DDD patterns and API design should not be assumed. The goal is to achieve API stability (‘service layer’) and Bounded Context domain model flexibility (‘business logic layer’) in a decoupled fashion. This is accomplished by introducing an Interface Bounded Context as the basis for the Open-Host service or API, in combination with a Published Language. Aggregates belong to the business domain, and REST resources belong to the integration domain, and by definition are decoupled to ensure flexibility in domain models and stability in REST interfaces.

Domain-Driven Design and API endpoints

Endpoint identification is an important step in API Design. In our sector, we opt for fine-grained decomposition and define endpoints for Aggregates. We believe our APIs should align with Aggregates as well-scoped interface elements, while the Bounded Contexts establish a highly cohesive boundary for these Aggregates. A Bounded Context as API endpoint is too much coarse-grained, large and complex. An idea is to include the Bounded Context and Aggregate roots in the URI path of the API endpoint. When we apply this to Fowler’s polysemous Meter example, we get:

/customer-support/v1/meters (Meter in the context of grid and customer)

/asset-management/v1/meters (Meter in the context of the physical meter itself)

(where the v1 version identifier serves an illustrative purpose if other versioning strategies are preferred).

Other example of Bounded Context as part of the path component in the URI is in: ‘Patterns, Principles, and Practices of Domain-Driven Design. John Wiley & Sons, Inc, 2015’by S. Millett & N. Tune‘ (p274).

The downside is that a dynamic and changeable concept as a Bounded Context is included in a URI that ideally should be static. The advantage is that the modularization, scope and team ownership become transparent. This approach is compliant with RFC3986 and supports the hierarchy definition of the path component of the URI. At Enexis (the organization we work for), we have incorporated this pattern into our URI strategy. Our experience is that this scheme works out fine in a disciplined environment with enough intentional design.

For a deeper discussion on the relation of APIs and DDD, see other interesting publications from Olaf and his team:

We hope that this post inspires fellow API designers and developers to delve into Patterns for API Design and and engage with the weekly API design pattern miniseries on LinkedIn:

A pattern a week keeps away design smells and critique!

We think this book is a must-read for anyone involved in modern system design and we can confirm that this book helps us in all aspects of API design (and API design certainly qualifies sometimes as a wicked problem).

Other interesting references:

https://medium.com/olzzio/domain-driven-service-design-with-context-mapper-and-mdsl-d5a0fc6091c2. This demo shows how to advance from a set of user stories to OpenAPI specifications to API provider stubs via strategic and tactic DDD. It is a convenient entry point to get acquainted with open-source tools like Context Mapper and Microservice Domain-Specific Language (MDSL);
Principles of Web API Design by James Higginbotham: we really like this book! It introduces an iterative ADDR design process as the foundation for an agile development and an API-design-first approach. Patterns for API Design is designed to complement this and the patterns are assigned to the ADDR steps. The ADDR process loosely incorporates concepts and practices derived from DDD;
Learning Domain-Driven Design [Book] (oreilly.com ) by Vlad Khononov. We have very much enjoyed reading this book. A highly recommended read and not only for those who want to acquaint themselves with Domain-Driven Design. Highly readable, and in less than 300 pages, one of the most influential software engineering topics is explained thoroughly and comprehensibly;

Originally published on: https://www.linkedin.com/pulse/patterns-api-design-adoption-story-part-3-ton-donker/

Leave a Comment Cancel Reply