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

by Cesare Pautasso, Daniel Lubke, Mirko Stocker, Olaf Zimmermann, Uwe Zdun

Length: 544 pages
Edition: 1
Language: English
Publisher: Addison-Wesley Professional
Publication Date: 2022-11-18
ISBN-10: 0137670109
ISBN-13: 9780137670109
Sales Rank: #684150 (See Top 100 Books)

Proven Patterns for Designing Evolvable High-Quality APIs–For Any Domain, Technology, or Platform

“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

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

Cover Page
About This eBook
Halftitle Page
Title Page
Copyright Page
Pearson’s Commitment to Diversity, Equity, and Inclusion
Contents
Foreword by Vaughn Vernon, Series Editor
Foreword by Frank Leymann
Preface
    Motivation
    Target Audience
    Patterns as Knowledge Sharing Vehicles
Acknowledgments
About the Authors
Part 1: Foundations and Narratives
    Chapter 1: Application Programming Interface (API) Fundamentals
        From Local Interfaces to Remote APIs
        Decision Drivers in API Design
        A Domain Model for Remote APIs
        Summary
    Chapter 2: Lakeside Mutual Case Study
        Business Context and Requirements
        Architecture Overview
        API Design Activities
        Target API Specification
        Summary
    Chapter 3: API Decision Narratives
        Prelude: Patterns as Decision Options, Forces as Decision Criteria
        Foundational API Decisions and Patterns
        Decisions about API Roles and Responsibilities
        Selecting Message Representation Patterns
        Interlude: Responsibility and Structure Patterns in the Lakeside Mutual Case
        Governing API Quality
        Deciding for API Quality Improvements
        Decisions about API Evolution
        Summary
Part 2: The Patterns
    Chapter 4: Pattern Language Introduction
        Positioning and Scope
        Patterns: Why and How?
        Navigating through the Patterns
        Foundations: API Visibility and Integration Types
        Basic Structure Patterns
        Summary
    Chapter 5: Define Endpoint Types and Operations
        Introduction to API Roles and Responsibilities
        Endpoint Roles (aka Service Granularity)
        Operation Responsibilities
        Summary
    Chapter 6: Design Request and Response Message Representations
        Introduction to Message Representation Design
        Element Stereotypes
        Special-Purpose Representations
        Summary
    Chapter 7: Refine Message Design for Quality
        Introduction to API Quality
        Message Granularity
        Client-Driven Message Content (aka Response Shaping)
        Message Exchange Optimization (aka Conversation Efficiency)
        Summary
    Chapter 8: Evolve APIs
        Introduction to API Evolution
        Versioning and Compatibility Management
        Life-Cycle Management Guarantees
        Summary
    Chapter 9: Document and Communicate API Contracts
        Introduction to API Documentation
        Documentation Patterns
        Summary
Part 3: Our Patterns in Action (Now and Then)
    Chapter 10: Real-World Pattern Stories
        Large-Scale Process Integration in the Swiss Mortgage Business
        Offering and Ordering Processes in Building Construction
        Summary
    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
    Cheat Sheet for Pattern Selection
    “Driven” API Design
Appendix B. Implementation of the Lakeside Mutual Case
    Pattern Application
    Java Service Layer
    OpenAPI Specification and Sample API Client
Appendix C. Microservice Domain-Specific Language (MDSL)
    Getting Started with MDSL
    MDSL Reference
    Summary of Support for Microservice API Patterns
    MDSL Tools
    Online Resources
Bibliography
Index
Code Snippets