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

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

by Olaf Zimmermann, Mirko Stocker, Daniel Lubke, Uwe Zdun, Cesare Pautasso
Released November 2022
Publisher(s): Addison-Wesley Professional
ISBN: 9780137670093

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

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

..

Table of contents

  1. Cover Page
  2. About This eBook
  3. Halftitle Page
  4. Title Page
  5. Copyright Page
  6. Pearson’s Commitment to Diversity, Equity, and Inclusion
  7. Contents
  8. Foreword by Vaughn Vernon, Series Editor
  9. Foreword by Frank Leymann
  10. Preface
    1. Motivation
    2. Target Audience
    3. Patterns as Knowledge Sharing Vehicles
  11. Acknowledgments
  12. About the Authors
  13. 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. Summary
  14. 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: Define 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: Design 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 (aka Response Shaping)
      4. Message Exchange Optimization (aka Conversation Efficiency)
      5. Summary
    5. Chapter 8: Evolve APIs
      1. Introduction to API Evolution
      2. Versioning and Compatibility Management
      3. Life-Cycle Management Guarantees
      4. Summary
    6. Chapter 9: Document and Communicate API Contracts
      1. Introduction to API Documentation
      2. Documentation Patterns
      3. Summary
  15. 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. Offering and Ordering Processes in Building Construction
      3. Summary
    2. Chapter 11: Conclusion
      1. Short Retrospective
      2. API Research: Refactoring to Patterns, MDSL, and More
      3. The Future of APIs
      4. Additional Resources
      5. Final Remarks
  16. Appendix A. Endpoint Identification and Pattern Selection Guides
    1. Cheat Sheet for Pattern Selection
    2. “Driven” API Design
  17. Appendix B. Implementation of the Lakeside Mutual Case
    1. Pattern Application
    2. Java Service Layer
    3. OpenAPI Specification and Sample API Client
  18. 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
  19. Bibliography
  20. Index
  21. Code Snippets

Product information

  • Title: Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges
  • Author(s): Olaf Zimmermann, Mirko Stocker, Daniel Lubke, Uwe Zdun, Cesare Pautasso
  • Release date: November 2022
  • Publisher(s): Addison-Wesley Professional
  • ISBN: 9780137670093