Chapter 11
Conclusion
Let us recapitulate the book content and reflect on the patterns for API design and evolution as we presented them across its three parts. This chapter also points to related research and contains our—somewhat speculative and risky—take on the future of APIs and related architectural knowledge.
Distributed systems are the norm today. In such systems, a number of services work together and communicate through remote APIs. When being assembled into distributed applications, APIs and their implementations must satisfy rather diverse integration requirements—different APIs may use different communication protocols and message exchange formats, their implementation components may reside in different security zones and/or run in different locations, and so on. Different options are available to fine-tune the message and endpoint design according to desired qualities and existing constraints. For instance, APIs often must be responsive, scalable and reliable but also readily developer-friendly and evolvable. Many of them automate business processes and activities involving customers, products, and business partners; such business activities and their supporting software frequently change in response to changes in their functional requirements and quality goals.
The purpose of the pattern language presented in this book is to help integration architects, API developers, and other roles involved with API design and evolution make more informed, adequate, and sound decisions when crafting APIs for a particular client community with its goals and domain contexts. Our patterns provide proven design options for these decisions.
Short Retrospective
We presented 44 patterns for API design and evolution, including rather common ones such as PAGINATION (Chapter 7) and API DESCRIPTION (Chapter 9) but also less obvious ones such as CONTEXT REPRESENTATION (Chapter 6) and TWO IN PRODUCTION (Chapter 8). Chapter 4 provided a language overview and patterns to scope APIs and structure messages, including FRONTEND INTEGRATION and PARAMETER TREE.
We assume that the APIs that apply these patterns exchange plain text messages rather than remote objects. They may do so over synchronous communication channels or asynchronous, queue-based ones. Selected patterns are implemented in the Lakeside Mutual sample application introduced in Chapter 2 and in the two real-world cases featured in Chapter 10. While many motivating examples and known uses of the patterns came from microservice-oriented systems, all software systems that contain remote APIs may benefit from applying them.
Did we miss some patterns? Certainly. For instance, reactive, long-running, event-driven API designs were only touched upon—these topics could fill an entire book. It would also be interesting to mine patterns on advanced composite structures that carry certain domain-specific semantics such as resource reservations, overview-details presentations, or case management activities. One could think of turning Martin Fowler’s Analysis Patterns [Fowler 1996] into pre-canned API designs. Books on data modeling [Hay 1996] could provide input to such effort, and common data definition initiatives such as microformats [Microformats 2022] and Schema.org1 would have their role to play too. Business responsibility-driven design could take a prominent place in such “domain API” undertaking.
On the API realization level, we could distinguish aggregated, mediating “guard resources” calling other APIs from self-contained “ground resources” that do not depend on other APIs provided elsewhere. We could also continue to work on patterns about API orchestration flows or conversations [Pautasso 2016]. Another time—maybe. While we hinted at API implementation options, we did not cover topics such as system transactions versus business-level compensation (ACID guarantees versus various forms of BASE properties) much; “Sagas” [Richardson 2018] or “Try-Confirm/Cancel” steps [Pardon 2011] could possibly support business-level compensation.
We only touched upon protocol specifics in examples and discussion sections; the recipes in the RESTful Web Services Cookbook [Allamaraju 2010] and many other books provide detailed advice regarding RESTful HTTP. The preface provided information about related pattern languages and other good reads.
We also did not put much emphasis on operating API implementations; just like any application deployment, API implementations have to be managed at runtime. There are many deployment and hosting options for API implementations and service-oriented systems, including serverless functions and other cloud computing offerings. API endpoints and, possibly, API gateways, have to be configured, secured, accounted for, and monitored (for instance, with regard to faults and performance). These activities fall under API management, a term that summarizes a suite of practices and tools complementary to API design and evolution.2
API Research: Refactoring to Patterns, MDSL, and More
“API first” design on a greenfield is one thing, but what if production APIs encounter quality problems? A survey conducted by two of us showed that quality deficits and changes in functional requirements might trigger API changes just as existing and new requirements do [Stocker 2021a].
One approach to improving the quality aspects of a software system and preparing for functional changes is refactoring. Refactoring is the practice of improving a software system without changing its external, observable behavior. A code refactoring cleans up a piece of code, for instance, renaming classes and methods to increase their understandability or breaking up a long piece of code into several parts for better maintainability.
API refactoring extends the notion of code refactoring (and stretches the meaning of the term somewhat):
An API refactoring evolves the remote interface of a system without changing its feature set and its semantics to improve at least one quality attribute.
An “Interface Refactoring Catalog” [Stocker 2021b] is emerging at the time of writing. The purpose of a refactoring can (but does not have to) be the alignment of the software with a design pattern [Kerievsky 2004]; not surprisingly, the Interface Refactoring Catalog references and suggests many of the patterns from this book. Examples of refactorings to API patterns in the catalog are “Add Wish List,” “Introduce Pagination,” and “Externalize Context.”
Many of the refactorings from the catalog are supported in the Microservice Domain Specific Language (MDSL) Tools. This is possible because, as shown in Appendix C, MDSL starts from our API domain model (introduced in Chapter 1) and features all of our patterns (from Chapters 4 to 9) one way or another, often as decorators of specification elements such as API endpoints, operations, and message representation elements.
2. It seems that we just had the second round of buzzword bingo in this book. Do you remember the first one?
Four of us worked on patterns on the relation of APIs to domain-driven design (DDD); two examples are “Domain Model Facade as API” and “Aggregate Roots as API Endpoints” [Singjai 2021a; Singjai 2021b; Singjai 2021c]. To support this transition, research on approaches for modeling APIs in relation to domain models and detecting the API-to-DDD mapping patterns in models is ongoing. API analytics research is another promising direction, yielding new patterns such as “Mutable Collection Resource” [Serbout 2021].
The Future of APIs
It is well known that it is hard to predict the future. At the time of writing, it is difficult to imagine that HTTP will go away. HTTP/2, a major revision of the original protocol, has been under standardization since 2015, and HTTP/3, the next proposed successor, reached the status of a “Proposed Standard” in June 2022 as well. In the last few years, we also saw additional protocols being introduced, some of which use HTTP/2 internally; gRPC is one prominent example. Even if protocols change, message verbosity and service granularity, and coupling/decoupling of communicating parties, will continue to keep API designers busy, particularly those of APIs and their clients operating in resource-constrained environments. Hardware improves, but history has taught us that client expectations grow with the progress that the hardware makes.
Message exchange formats seem to come and go more frequently than protocols; for example, XML went out of fashion, and JSON dominates at the time of writing. However, there was a time when XML was considered the ultimate and final stage of the evolution of markup languages. Will we ever abandon JSON, and if so, what comes next? We do not have answers to these questions but are quite confident that patterns related to message design, for instance, EMBEDDED ENTITY and LINKED INFORMATION HOLDER, will continue to be relevant—also to API design leveraging the next generations of formats (if any).3
OpenAPI Specification is the dominant API description language for HTTP-based APIs at present. AsyncAPI is gaining importance as a similar approach to describe message-based APIs. MDSL has bindings and generator support for OpenAPI Specification and AsyncAPI, as well as for other contemporary API description languages. Will additional API description languages emerge and sustain, covering the two prevailing integration camps (synchronous and asynchronous communication) as well as other integration technologies and protocols? Is there a chance for a unified language? Time will tell, and we look forward to finding known uses of our patterns in these languages and API designs using them.
3. Maybe some semi-intelligent, format-autonomous tools can automate their application in the future?
Additional Resources
The Web site companion to this book provides pattern summaries and additional background information:
The Interface Refactoring Catalog is available here:
https://interface-refactoring.github.io
The “Stepwise Service Design” activity proposed in the software and service Design Practice Reference (DPR) leverages many of the patterns from this book [Zimmermann 2021b]. DPR also comes as an open-source repository of methods and practices that are applicable to service analysis and design:
Final Remarks
While IT buzzwords and technology concepts come and go, integration styles and design patterns stay. Patterns are not final solutions but can help you do better and avoid common mistakes—so that you have an opportunity to make new ones, which then become lessons learned and, eventually, lead to new patterns or antipatterns. Please view our patterns as a starting point for your design endeavors, not as their destination!
We are confident that the architectural knowledge captured in this book and its patterns has the potential to guide architectural decisions on your real-world API design and development projects. If this actually happens, we will be happy to get your feedback on how the patterns helped you craft awesome APIs.
Thanks for buying, reading, and making it to the end of our book!
Olaf, Mirko, Daniel, Uwe, and Cesare
June 30, 2022