Foreword by Vaughn Vernon, Series Editor
Foreword by Frank Leymann
Preface
Acknowledgments
About the Authors
Part 1: Foundations and Narratives
Chapter 1: Application Programming Interface (API) Fundamentals
From Local Interfaces to Remote APIs
A Bit of Distribution and Remoting History
Remote API: Access to Services via Protocol for Integration
APIs Matter
Decision Drivers in API Design
What Makes an API Successful?
How Do API Designs Differ?
What Makes API Design Challenging?
Architecturally Significant Requirements
Developer Experience
A Domain Model for Remote APIs
Communication Participants
Endpoints Offer Contracts Describing Operations
Messages as Conversation Building Blocks
Message Structure and Representation
API Contract
Domain Model Usage throughout the Book
Summary
Chapter 2: Lakeside Mutual Case Study
Business Context and Requirements
User Stories and Desired Qualities
Analysis-Level Domain Model
Architecture Overview
System Context
Application Architecture
API Design Activities
Target API Specification
Chapter 3: API Decision Narratives
Prelude: Patterns as Decision Options, Forces as Decision Criteria
Foundational API Decisions and Patterns
API Visibility
API Integration Types
Documentation of the API
Decisions about API Roles and Responsibilities
Architectural Role of an Endpoint
Refining Information Holder Roles
Defining Operation Responsibilities
Selecting Message Representation Patterns
Flat versus Nested Structure of Representation Elements
Element Stereotypes
Interlude: Responsibility and Structure Patterns in the Lakeside Mutual Case
Governing API Quality
Identification and Authentication of the API Client
Metering and Charging for API Consumption
Preventing API Clients from Excessive API Usage
Explicit Specification of Quality Objectives and Penalties
Communication of Errors
Explicit Context Representation
Deciding for API Quality Improvements
Pagination
Other Means of Avoiding Unnecessary Data Transfer
Handling Referenced Data in Messages
Decisions about API Evolution
Versioning and Compatibility Management
Strategies for Commissioning and Decommissioning
Interlude: Quality and Evolution Patterns in the Lakeside Mutual Case
Part 2: The Patterns
Chapter 4: Pattern Language Introduction
Positioning and Scope
Patterns: Why and How?
Navigating through the Patterns
Structural Organization: Find Patterns by Scope
Theme Categorization: Search for Topics
Time Dimension: Follow Design Refinement Phases
How to Navigate: The Map to MAP
Foundations: API Visibility and Integration Types
Pattern: FRONTEND INTEGRATION
Pattern: BACKEND INTEGRATION
Pattern: PUBLIC API
Pattern: COMMUNITY API
Pattern: SOLUTION-INTERNAL API
Foundation Patterns Summary
Basic Structure Patterns
Pattern: ATOMIC PARAMETER
Pattern: ATOMIC PARAMETER LIST
Pattern: PARAMETER TREE
Pattern: PARAMETER FOREST
Basic Structure Patterns Summary
Chapter 5: Define Endpoint Types and Operations
Introduction to API Roles and Responsibilities
Challenges and Desired Qualities
Patterns in this Chapter
Endpoint Roles (aka Service Granularity)
Pattern: PROCESSING RESOURCE
Pattern: INFORMATION HOLDER RESOURCE
Pattern: OPERATIONAL DATA HOLDER
Pattern: MASTER DATA HOLDER
Pattern: REFERENCE DATA HOLDER
Pattern: LINK LOOKUP RESOURCE
Pattern: DATA TRANSFER RESOURCE
Operation Responsibilities
Pattern: STATE CREATION OPERATION
Pattern: RETRIEVAL OPERATION
Pattern: STATE TRANSITION OPERATION
Pattern: COMPUTATION FUNCTION
Chapter 6: Design Request and Response Message Representations
Introduction to Message Representation Design
Challenges When Designing Message Representations
Pattern: DATA ELEMENT
Pattern: METADATA ELEMENT
Pattern: ID ELEMENT
Pattern: LINK ELEMENT
Special-Purpose Representations
Pattern: API KEY
Pattern: ERROR REPORT
Pattern: CONTEXT REPRESENTATION
Chapter 7: Refine Message Design for Quality
Introduction to API Quality
Challenges When Improving API Quality
Patterns in This Chapter
Message Granularity
Pattern: EMBEDDED ENTITY
Pattern: LINKED INFORMATION HOLDER
Client-Driven Message Content (aka Response Shaping)
Pattern: PAGINATION
Pattern: WISH LIST
Pattern: WISH TEMPLATE
Message Exchange Optimization (aka Conversation Efficiency)
Pattern: CONDITIONAL REQUEST
Pattern: REQUEST BUNDLE
Chapter 8: Evolve APIs
Introduction to API Evolution
Challenges When Evolving APIs
Pattern: VERSION IDENTIFIER
Pattern: SEMANTIC VERSIONING
Life-Cycle Management Guarantees
Pattern: EXPERIMENTAL PREVIEW
Pattern: AGGRESSIVE OBSOLESCENCE
Pattern: LIMITED LIFETIME GUARANTEE
Pattern: TWO IN PRODUCTION
Chapter 9: Document and Communicate API Contracts
Introduction to API Documentation
Challenges When Documenting APIs
Documentation Patterns
Pattern: API DESCRIPTION
Pattern: PRICING PLAN
Pattern: RATE LIMIT
Pattern: SERVICE LEVEL AGREEMENT
Part 3: Our Patterns in Action (Now and Then)
Chapter 10: Real-World Pattern Stories
Large-Scale Process Integration in the Swiss Mortgage Business
Business Context and Domain
Technical Challenges
Role and Status of API
Pattern Usage and Implementation
Retrospective and Outlook
Offering and Ordering Processes in Building Construction
Chapter 11: Conclusion
Short Retrospective
API Research: Refactoring to Patterns, MDSL, and More
The Future of APIs
Additional Resources
Final Remarks
Appendix A: Endpoint Identification and Pattern Selection Guides
Appendix B: Implementation of the Lakeside Mutual Case
Appendix C: Microservice Domain-Specific Language (MDSL)
Bibliography
Index
3.15.172.195