Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, 1st edition
- Olaf Zimmermann |
- Mirko Stocker |
- Daniel Lubke |
- Uwe Zdun |
- Cesare Pautasso |
Title overview
As thousands of developers focus on constructing reliable, well-performing, and secure APIs, there's immense demand for a practical, up-to-date, technology-and-platform-independent guide to API design. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges fills this gap. A team of expert authors cut through the complexity of API communication and message content, presenting rich and complete design guidelines and heuristics for engineering APIs sustainably and specifying them clearly.
Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges covers the entire API lifecycle, from launching projects and establishing business goals through defining architecturally significant requirements, elaborating and implementing designs, and documentation. It illuminates patterns drawn from both public web APIs and proprietary application development and software integration projects the authors have led or participated in. You'll find a complete library of concrete, actionable design patterns, each formatted consistently to explain context, forces, problem, solution, discussion, and known uses.
Throughout, the authors share practical insights for making better design decisions and tradeoffs, facilitating easier implementation, and structuring and designing higher-quality APIs to meet both short- and long-term needs. You'll learn how to:
- Facilitate better API design discussions by establishing a common vocabulary, identifying key decisions, and comparing realistic options
- Simplify design reviews and accelerate objective comparisons
- Plan to smoothly evolve and extend APIs without compromising backward-compatibility
- Enhance documentation with useful design knowledge to help client developers quickly grasp API capabilities and constraints, and confidently use your APIs
Table of contents
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
Author bios
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.