Patterns for API Design: Addison-Wesley Signature Series (Vernon)

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

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 Softwares 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.