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