Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, 1st edition
Published by Addison-Wesley Professional (November 8, 2022) © 2023
- Olaf Zimmermann
- Mirko Stocker
- Daniel Lubke
- Uwe Zdun
- Cesare Pautasso
eTextbook
- Available for purchase from all major ebook resellers, including InformIT.com.
- To request a review copy, click on the "Request a Review Copy" button.
- A print text (hardcover or paperback)Â
- Free shipping
- Also available for purchase as an ebook from all major ebook resellers, including InformIT.com
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
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 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.
Need help? Get in touch