Published by Addison-Wesley Professional (December 26, 2022) © 2023
Olaf Zimmermann | Mirko Stocker | Daniel Lubke | Uwe Zdun | Cesare PautassoProven Patterns for Designing Evolvable High-Quality APIs--For Any Domain, Technology, or Platform
APIs enable breakthrough innovation and digital transformation in organizations and ecosystems of all kinds. To create user-friendly, reliable and well-performing APIs, architects, designers, and developers need expert design guidance. This practical guide cuts through the complexity of API conversations and their message contents, introducing comprehensive guidelines and heuristics for designing APIs sustainably and specifying them clearly, for whatever technologies or platforms you use.
In Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, five expert architects and developers cover the entire API lifecycle, from launching projects and establishing goals through defining requirements, elaborating designs, planning evolution, and creating useful documentation. They crystallize the collective knowledge of many practitioners into 44 API design patterns, consistently explained with context, pros and cons, conceptual solutions, and concrete examples. To make their pattern language accessible, they present a domain model, a running case study, decision narratives with pattern selection options and criteria, and walkthroughs of real-world projects applying the patterns in two different industries.
- Identify and overcome API design challenges with patterns
- Size your endpoint types and operations adequately
- Design request and response messages and their representations
- Refine your message design for quality
- Plan to evolve your APIs
- Document and communicate your API contracts
- Combine patterns to solve real-world problems and make the right tradeoffs
"This book provides a healthy mix of theory and practice, containing numerous nuggets of deep advice but never losing the big picture . . . grounded in real-world experience and documented with academic rigor applied and practitioner community feedback incorporated. I am confident that [it] will serve the community well, today and tomorrow."
--Prof. Dr. Dr. h. c. Frank Leymann, Managing Director, Institute of Architecture of Application Systems, University of Stuttgart
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