,Table of Contents
1. Foreword by Frank Leymann
2. Preface
1. Motivation
2. Target Audience
3. Patterns as Knowledge Sharing Vehicles
3. Acknowledgements
4. About the Authors
5. Part 1: Foundations and Narratives
1. Chapter 1. Application Programming Interface (API) Fundamentals
1. From Local Interfaces to Remote APIs
2. Decision Drivers in API Design
3. A Domain Model for Remote APIs
4. Summary
2. Chapter 2. Lakeside Mutual Case Study
1. Business Context and Requirements
2. Architecture Overview
3. API Design Activities
4. Target API Specification
5. Summary
3. Chapter 3. API Decision Narratives
1. Prelude: Patterns as Decision Options, Forces as Decision Criteria
2. Foundational API Decisions and Patterns
3. Decisions about API Roles and Responsibilities
4. Selecting Message Representation Patterns
5. Interlude: Responsibility and Structure Patterns in the Lakeside Mutual
Case
6. Governing API Quality
7. Deciding for API Quality Improvements
8. Decisions about API Evolution
9. Interlude: Quality and Evolution Patterns in the Lakeside Mutual Case
10. Summary
6. Part 2: The Patterns
1. Chapter 4. Pattern Language Introduction
1. Positioning and Scope
2. Patterns: Why and How?
3. Navigating through the Patterns
4. Foundations: API Visibility and Integration Types
5. Basic Structure Patterns
6. Summary
2. Chapter 5. Defining Endpoint Types and Operations
1. Introduction to API Roles and Responsibilities
2. Endpoint Roles (aka Service Granularity)
3. Operation Responsibilities
4. Summary
, 3. Chapter 6. Designing Request and Response Message Representations
1. Introduction to Message Representation Design
2. Element Stereotypes
3. Special-Purpose Representations
4. Summary
4. Chapter 7. Refine Message Design for Quality
1. Introduction to API Quality
2. Message Granularity
3. Client-Driven Message Content
4. Message Exchange Optimization (aka Conversation Efficiency)
5. Summary
5. Chapter 8. Evolve API
1. Introduction to API Evolution
2. Versioning and Compatibility Management
3. Life-Cycle Management Guarantees
4. Summary
6. Chapter 9. Document and Communicate API Contract
1. Introduction to API Documentation
2. Documentation Patterns
3. Summary
7. Part 3: Our Patterns in Action (Now and Then)
1. Chapter 10. Real-World Pattern Stories
1. Large-Scale Process Integration in the Swiss Mortgage Business
2. APIs for Offering and Ordering Processes in the Building Construction
Domain
3. Summary
2. Chapter 11. Conclusion (Closing Remarks)
1. Short Retrospective
2. API Research: Refactoring to Patterns, MDSL, and More
3. The Future of APIs
4. Additional Resources
5. Final Remarks
8. Appendix A: Endpoint Identification and Pattern Selection Guides
1. Cheat Sheet for Pattern Selection
2. “Driven” API Design
9. Appendix B: Implementation of the Lakeside Mutual Case
1. Pattern Application
2. Java Service Layer
3. OpenAPI Specification and Sample API Client
10. Appendix C: Microservice Domain-Specific Language (MDSL)
1. Getting Started with MDSL
2. MDSL Reference
3. Summary of Support for Microservice API Patterns
4. MDSL Tools
5. Online Resources
11. Bibliography
, The book has three parts: Part 1, “Foundations and Narratives,” Part 2, “The
Patterns,” and Part 3, “Our Patterns in Action (Now and Then).” Figure P.1 shows these parts
with their chapters and logical dependencies.
Figure P.1 Book parts and their dependencies
Part 1 introduces the domain of API design conceptually, starting with Chapter 1, “Application
Programming Interface (API) Fundamentals.” Lakeside Mutual, our case study and primary
source of examples, appears for the first time with its business context, requirements, existing
systems, and initial API design in Chapter 2, “Lakeside Mutual Case Study.” We provide
decision models that show how the patterns in our language relate to each other in Chapter 3,
“API Decision Narratives.” Chapter 3 also provides pattern selection criteria and shows how the
featured decisions were made in the Lakeside Mutual case. These decision models may serve as
navigation aids when reading the book and when applying the patterns in practice.
Part 2 is the pattern reference; it starts with Chapter 4, “Pattern Language
Introduction,” followed by five chapters full of patterns: Chapter 5, “Define Endpoint Types
and Operations,” Chapter 6, “Design Request and Response Message
Representations,” Chapter 7, “Refine Message Design for Quality,” Chapter 8, “Evolve
APIs,” and Chapter 9, “Document and Communicate API Contract.” Figure P.2 illustrates
these chapters and possible reading paths in this part; for instance, you can learn about basic
structure patterns such as ATOMIC PARAMETER and PARAMETER TREE in Chapter 4 and then move
on to element stereotypes such as ID ELEMENT and METADATA ELEMENT found in Chapter 6.
1. Foreword by Frank Leymann
2. Preface
1. Motivation
2. Target Audience
3. Patterns as Knowledge Sharing Vehicles
3. Acknowledgements
4. About the Authors
5. Part 1: Foundations and Narratives
1. Chapter 1. Application Programming Interface (API) Fundamentals
1. From Local Interfaces to Remote APIs
2. Decision Drivers in API Design
3. A Domain Model for Remote APIs
4. Summary
2. Chapter 2. Lakeside Mutual Case Study
1. Business Context and Requirements
2. Architecture Overview
3. API Design Activities
4. Target API Specification
5. Summary
3. Chapter 3. API Decision Narratives
1. Prelude: Patterns as Decision Options, Forces as Decision Criteria
2. Foundational API Decisions and Patterns
3. Decisions about API Roles and Responsibilities
4. Selecting Message Representation Patterns
5. Interlude: Responsibility and Structure Patterns in the Lakeside Mutual
Case
6. Governing API Quality
7. Deciding for API Quality Improvements
8. Decisions about API Evolution
9. Interlude: Quality and Evolution Patterns in the Lakeside Mutual Case
10. Summary
6. Part 2: The Patterns
1. Chapter 4. Pattern Language Introduction
1. Positioning and Scope
2. Patterns: Why and How?
3. Navigating through the Patterns
4. Foundations: API Visibility and Integration Types
5. Basic Structure Patterns
6. Summary
2. Chapter 5. Defining Endpoint Types and Operations
1. Introduction to API Roles and Responsibilities
2. Endpoint Roles (aka Service Granularity)
3. Operation Responsibilities
4. Summary
, 3. Chapter 6. Designing Request and Response Message Representations
1. Introduction to Message Representation Design
2. Element Stereotypes
3. Special-Purpose Representations
4. Summary
4. Chapter 7. Refine Message Design for Quality
1. Introduction to API Quality
2. Message Granularity
3. Client-Driven Message Content
4. Message Exchange Optimization (aka Conversation Efficiency)
5. Summary
5. Chapter 8. Evolve API
1. Introduction to API Evolution
2. Versioning and Compatibility Management
3. Life-Cycle Management Guarantees
4. Summary
6. Chapter 9. Document and Communicate API Contract
1. Introduction to API Documentation
2. Documentation Patterns
3. Summary
7. Part 3: Our Patterns in Action (Now and Then)
1. Chapter 10. Real-World Pattern Stories
1. Large-Scale Process Integration in the Swiss Mortgage Business
2. APIs for Offering and Ordering Processes in the Building Construction
Domain
3. Summary
2. Chapter 11. Conclusion (Closing Remarks)
1. Short Retrospective
2. API Research: Refactoring to Patterns, MDSL, and More
3. The Future of APIs
4. Additional Resources
5. Final Remarks
8. Appendix A: Endpoint Identification and Pattern Selection Guides
1. Cheat Sheet for Pattern Selection
2. “Driven” API Design
9. Appendix B: Implementation of the Lakeside Mutual Case
1. Pattern Application
2. Java Service Layer
3. OpenAPI Specification and Sample API Client
10. Appendix C: Microservice Domain-Specific Language (MDSL)
1. Getting Started with MDSL
2. MDSL Reference
3. Summary of Support for Microservice API Patterns
4. MDSL Tools
5. Online Resources
11. Bibliography
, The book has three parts: Part 1, “Foundations and Narratives,” Part 2, “The
Patterns,” and Part 3, “Our Patterns in Action (Now and Then).” Figure P.1 shows these parts
with their chapters and logical dependencies.
Figure P.1 Book parts and their dependencies
Part 1 introduces the domain of API design conceptually, starting with Chapter 1, “Application
Programming Interface (API) Fundamentals.” Lakeside Mutual, our case study and primary
source of examples, appears for the first time with its business context, requirements, existing
systems, and initial API design in Chapter 2, “Lakeside Mutual Case Study.” We provide
decision models that show how the patterns in our language relate to each other in Chapter 3,
“API Decision Narratives.” Chapter 3 also provides pattern selection criteria and shows how the
featured decisions were made in the Lakeside Mutual case. These decision models may serve as
navigation aids when reading the book and when applying the patterns in practice.
Part 2 is the pattern reference; it starts with Chapter 4, “Pattern Language
Introduction,” followed by five chapters full of patterns: Chapter 5, “Define Endpoint Types
and Operations,” Chapter 6, “Design Request and Response Message
Representations,” Chapter 7, “Refine Message Design for Quality,” Chapter 8, “Evolve
APIs,” and Chapter 9, “Document and Communicate API Contract.” Figure P.2 illustrates
these chapters and possible reading paths in this part; for instance, you can learn about basic
structure patterns such as ATOMIC PARAMETER and PARAMETER TREE in Chapter 4 and then move
on to element stereotypes such as ID ELEMENT and METADATA ELEMENT found in Chapter 6.
