This article is a continuation of my previous LinkedIn publication “Patterns for API Design: Adoption Story Part 1” where I expressed my enthusiasm for the oustanding book “Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges” co-authored by: Olaf Zimmermann, Mirko Stocker, Daniel Luebke, Uwe Zdun and Cesare Pautasso. The book was published in November 2022.
Swiss army knife
Patterns for API Design is both a catalog of design patterns (44 in total) and it presents a pattern language aiming at a ubiquitous language for establishing an API design vocabulary. Every pattern is consistently explained with context, pros and cons, conceptual solutions, and concrete examples.
Acquiring knowledge about these patterns and their respective pros and cons will significantly enhance proficiency in API design and evolution. This knowledge is crucial for adopting a design-first approach. APIs and the services they provide will be simpler to develop, consume, and evolve when applying patterns from this book suited for a particular requirements context.
The book provides a healthy mix of theory and practice: alongside the comprehensive documentation of the patterns it shows pattern application and combination in real-world systems. To keep it brief and to the point (and referring to the Swiss nationality of two of the authors 😉) we would like to quote the following statement from the book:
The book Patterns for API Design is the Swiss army knife for software engineers and architects when it comes to designing, evolving, and documenting APIs (Uwe van Heesch)
A pattern a week…
Weekly featured patterns per theme category
Since March 2023, Olaf and Mirko have initiated the weekly design pattern series on LinkedIn (). Each week, a new pattern is featured and at the time of this writing 14 patterns have already been presented. See the overview on the right. This implies that we still have 30 more patterns to cover in order to comprehensively feature all 44 design patterns documented in the book. It’s interesting and enjoyable to observe the LinkedIn comments from the API design community on the API Pattern of the Week episodes. This emphasizes the significance of API design and the numerous challenges it entails in enhancing API quality. Following the weekly mini-series and delving into the forces, contexts and known uses of each pattern will undeniably improve your API design capability:
A pattern a week will improve your API design technique!
Pattern categories
As depicted in the figure above, the patterns are grouped into five categories: Foundation, Responsibility, Structure, Quality and Evolution. Each category answers several related topical questions and deals with a specific set of interconnected design considerations.
Another approach to organizing the patterns is based on architectural scope, including: API as a whole, endpoint, operation, and message. See the figure below, which outlines the 14 featured patterns of the week arranged according to their respective scopes:
Weekly featured patterns per architectural scope
Just as a Swiss Army knife is designed to serve multiple purposes, grouping and categorizing the patterns in various ways also serves multiple purposes. The patterns can be grouped based on lifecycle phase, level of abstraction and refinement, and type of design concern. Each of these resulting categories delves into a cluster of related design considerations. The various options for guiding through the patterns are tremendously helpful for navigating the patterns. See the different categories and pattern filters on:
https://api-patterns.org/categories
Practitioner-community feedback
Patterns for API Design is currently being enthusiastically read by the API Design working group within the Dutch Energy Sector (which is my field of work). Our design guidelines are closely aligned with the API design principles and recommendations of the Dutch Government. Feedback from the API Design working group on the weekly design patterns is sent to Olaf en Mirko and published as an adoption story on api-patterns.org. We are inspired and convinced that we can benefit from the architectural knowledge captured in the book and its patterns. Takeways are (to mention a few with more to follow):
- proposed pattern language and the connection with RDD, DDD and #ADDR
- the distinct architecture roles of endpoints and the subdivision of the Information Holder Resource
- categorization of operation responsibilities
- template for Elaborate API descriptions covering both business information and functional-technical API design concerns
- call to actions: mapping design tasks to the presented pattern categories
- immense treasure of known uses
- DX – Developer eXperience and the importance of ‘first impression lasts’. We greatly appreciate Olaf’s API Design Review Checklist
- qualification of metadata (see feedback section below)
The four engaged readers of the Dutch Energy Sector API Design working group are (from left to right): Arthur Keesen (EDSN), Wouter Meijers (EDSN), Ton Donker (Enexis), Ruben Haasjes (Enexis):
Engaged and enthusiastic readers from the Dutch Energy sector
Please find below feedback on the Metadata Element pattern:
Usage of METADATA ELEMENTS (data about data) in context – original figure in the book
- Many RESTful API design books discuss metadata and the various methods of incorporating metadata into request and response messages. Apart from the standard protocol-level headers, metadata can also be included within the payload and reflected in status codes. While knowing how to transmit metadata is vital in API design, understanding the distinct types of metadata, their roles, purposes, and the kind of information each variant of metadata can offer is equally essential.
- So far, we have not seen an API design book in which metadata is qualified and categorized as is done in Patterns for API Design.
- According to this book, metadata is categorized into three primary types: control, aggregated, and provenance metadata elements. These categories respectively encompass: technical usage hints (identifiers, filters, API keys, hypermedia controls), statistics and calculations (page counters, total results), and description and provenance (version number, owner, location information).
- This classification approach provides a deeper comprehension of the specific metadata element’s purpose and role, along with the information it encapsulates. This benefits both providers and consumers, especially when dealing with custom protocol headers.
- By applying the Metadata Element pattern and adhering to its metadata qualifications, you can undoubtedly enhance the value of your API design. This, in turn, will facilitate more precise and consistent API usage since metadata is as important as the data itself.
Please refer to the complete adoption story as published on api-patterns.org: https://api-patterns.org/2023/08/25/pattern-adoption-story-1-part-2.html
We hope this LinkedIn post will inspire other API designers and developers to begin reading Patterns for API Design and to follow the weekly API design pattern mini-series on LinkedIn. The authors are open to more adoption stories from the community. In our opinion, Patterns for API Design is essential reading for anyone involved in contemporary system design.
Hats off to the authors of this outstanding book, and heartfelt thanks for the pleasant collaboration and for making the feedback publicly accessible on api-patterns.org!
Originally published on: https://www.linkedin.com/pulse/patterns-api-design-adoption-story-part-2-ton-donker/