Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges

Description

Proven 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

Sample Content

Sample Pages

Download the sample pages (includes Chapter 7)

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

Updates

Errata

We've made every effort to ensure the accuracy of this book and its companion content. Any errors that have been confirmed since this book was published can be downloaded below.

Download the errata (46 KB .doc)

Submit Errata