Patterns for API Design

Olaf Zimmermann is professor of software architecture at the Institute for Software at Eastern Switzerland University of Applied Sciences, Distinguished IT Architect at The Open Group, and co-editor of IEEE Software's Insights column. Mirko Stocker is professor of software engineering at Eastern Switzerland University of Applied Sciences, specializing on Web development and cloud solutions. Daniel Lübke is an independent coding and consulting architect who specializes in business process automation and digitization projects. Uwe Zdun is professor of software architecture at the University of Vienna, focusing on distributed systems engineering, DevOps, patterns, modeling, and empirical software engineering. Cesare Pautasso is a professor at the Università della Svizzera Italiana, where he leads the Architecture, Design, and Web Information Systems Engineering research group. The authors are active community members participating in pattern writer's workshops, shepherding other authors, serving on program committees, and chairing conferences.

• Foreword by Vaughn Vernon, Series Editor     xviiForeword by Frank Leymann     xxiPreface     xxiii  Part 1: Foundations and Narratives     1Chapter 1: Application Programming Interface (API) Fundamentals     3From Local Interfaces to Remote APIs     3Decision Drivers in API Design     14A Domain Model for Remote APIs     22Summary     28  Chapter 2: Lakeside Mutual Case Study     31Business Context and Requirements     31Architecture Overview     35API Design Activities     39Target API Specification     39Summary     41  Chapter 3: API Decision Narratives     43Prelude: Patterns as Decision Options, Forces as Decision Criteria     43Foundational API Decisions and Patterns     45Decisions about API Roles and Responsibilities     57Selecting Message Representation Patterns     70Interlude: Responsibility and Structure Patterns in the Lakeside Mutual Case     82Governing API Quality     84Deciding for API Quality Improvements     98Decisions about API Evolution     110Summary     122  Part 2: The Patterns     125Chapter 4: Pattern Language Introduction      127Positioning and Scope     128Patterns: Why and How?     130Navigating through the Patterns     131Foundations: API Visibility and Integration Types     137Basic Structure Patterns     146Summary     158  Chapter 5: Define Endpoint Types and Operations     161Introduction to API Roles and Responsibilities     162Endpoint Roles (aka Service Granularity)     167Operation Responsibilities     215Summary     248  Chapter 6: Design Request and Response Message Representations     253Introduction to Message Representation Design     253Element Stereotypes     256Special-Purpose Representations     282Summary                                                 305  Chapter 7: Refine Message Design for Quality  309Introduction to API Quality     309Message Granularity     313Client-Driven Message Content (aka Response Shaping)     325Message Exchange Optimization (aka Conversation Efficiency)     344Summary     355  Chapter 8: Evolve APIs     357Introduction to API Evolution     357Versioning and Compatibility Management     362Life-Cycle Management Guarantees     374Summary     393  Chapter 9: Document and Communicate API Contracts     395Introduction to API Documentation     395Documentation Patterns     398Summary     421    Part 3: Our Patterns in Action (Now and Then)     423Chapter 10: Real-World Pattern Stories     425Large-Scale Process Integration in the Swiss Mortgage Business     426Offering and Ordering Processes in Building Construction     438Summary     445  Chapter 11: Conclusion     447Short Retrospective     448API Research: Refactoring to Patterns, MDSL, and More     449The Future of APIs     450Additional Resources     451Final Remarks     451  Appendix A: Endpoint Identification and Pattern Selection Guides     453Appendix B: Implementation of the Lakeside Mutual Case     463Appendix C: Microservice Domain-Specific Language (MDSL)     471  Bibliography     483Index     499