Principles of Web API Design: Delivering Value with APIs and Microservices

Principles of Web API Design: Delivering Value with APIs and Microservices

by James Higginbotham
Released December 2021
Publisher(s): Addison-Wesley Professional
ISBN: 9780137355754

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

The Full-Lifecycle Guide to API Design

Principles of Web API Design brings together principles and processes to help you succeed across the entire API design lifecycle. Drawing on extensive in-the-trenches experience, leading consultant James Higginbotham helps you align every stakeholder on specific outcomes, design APIs that deliver value, and scale the design process from small teams to the entire organization.

Higginbotham helps you bring an "outside-in" perspective to API design to reflect the voices of customers and product teams, map requirements to specific and well-organized APIs, and choose the right API style for writing them. He walks through a real-world example from the ground up, offering guidance for anyone designing new APIs or extending existing APIs.

  • Deliver great APIs by getting your design processes right

  • Gain agreement on specific outcomes from design teams, customers, and other stakeholders

  • Craft job stories, conduct EventStorming, and model capabilities

  • Identify the right APIs, and organize operations into coherent API profiles

  • Choose the best styles for each project: REST, gRPC, GraphQL, or event-based async APIs

  • Refine designs based on feedback from documenters, testers, and customers

  • Decompose APIs into microservices

  • Mature your API program, implementing design and management processes that scale

This guide is invaluable for anyone involved in planning or building APIs--architects, developers, team leaders, managers in single and multi-team environments, and any technical or business professional delivering "API-as-a-product" offerings.

Register your book for convenient access to downloads, updates, and/or corrections as they become available. See inside book for details.

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. Dedication Page
  8. Contents
  9. Series Editor Foreword
  10. Foreword
  11. Preface
    1. Who Should Read This Book
    2. About This Book
    3. What’s Not in the Book
  12. Acknowledgments
  13. About the Author
  14. Part I: Introduction to Web API Design
    1. Chapter 1. The Principles of API Design
      1. The Elements of Web API Design
      2. API Design Is Communication
      3. Reviewing the Principles of Software Design
      4. Resource-Based API Design
      5. Resources Are Not Object or Domain Models
      6. Resource-Based APIs Exchange Messages
      7. The Principles of Web API Design
      8. Summary
    2. Chapter 2. Collaborative API Design
      1. Why an API Design Process?
      2. API Design Process Antipatterns
      3. The API Design-First Approach
      4. Remaining Agile with API Design-First
      5. The Align-Define-Design-Refine Process
      6. The Role of DDD in API Design
      7. API Design Involves Everyone
      8. Applying the Process Effectively
      9. Summary
  15. Part II: Aligning on API Outcomes
    1. Chapter 3. Identify Digital Capabilities
      1. Ensuring Stakeholder Alignment
      2. What Are Digital Capabilities?
      3. Focusing on the Jobs to Be Done
      4. What Are Job Stories?
      5. The Components of a Job Story
      6. Writing Job Stories for APIs
      7. Overcoming Job Story Challenges
      8. Techniques for Capturing Job Stories
      9. A Real-World API Design Project
      10. Job Story Examples
      11. Summary
    2. Chapter 4. Capture Activities and Steps
      1. Extending Job Stories into Activities and Steps
      2. Using EventStorming for Collaborative Understanding
      3. How EventStorming Works
      4. The Benefits of EventStorming
      5. Facilitating an EventStorming Session
      6. Summary
  16. Part III: Defining Candidate APIs
    1. Chapter 5. Identifying API Boundaries
      1. Avoiding API Boundary Antipatterns
      2. Bounded Contexts, Subdomains, and APIs
      3. Finding API Boundaries Using EventStorming
      4. Finding API Boundaries through Activities
      5. Naming and Scoping APIs
      6. Summary
    2. Chapter 6. API Modeling
      1. What Is API Modeling?
      2. The API Modeling Process
      3. Validating the API Model with Sequence Diagrams
      4. Evaluating API Priority and Reuse
      5. Summary
  17. Part IV: Designing APIs
    1. Chapter 7. REST-Based API Design
      1. What Is a REST-Based API?
      2. REST API Design Process
      3. Selecting a Representation Format
      4. Common REST Design Patterns
      5. Summary
    2. Chapter 8. RPC and Query-Based API Design
      1. What Is an RPC-Based API?
      2. RPC API Design Process
      3. What Is a Query-Based API?
      4. Query-Based API Design Process
      5. Summary
    3. Chapter 9. Async APIs for Eventing and Streaming
      1. The Problem with API Polling
      2. Async APIs Create New Possibilities
      3. A Review of Messaging Fundamentals
      4. Async API Styles
      5. Designing Async APIs
      6. Documenting Async APIs
      7. Summary
  18. Part V: Refining the API Design
    1. Chapter 10. From APIs to Microservices
      1. What Are Microservices?
      2. Microservices Reduce Coordination Costs
      3. The Difference between APIs and Microservices
      4. Weighing the Complexity of Microservices
      5. Synchronous and Asynchronous Microservices
      6. Microservice Architecture Styles
      7. Right-Sizing Microservices
      8. Decomposing APIs into Microservices
      9. Considerations When Transitioning to Microservices
      10. Summary
    2. Chapter 11. Improving the Developer Experience
      1. Creating a Mock API Implementation
      2. Providing Helper Libraries and SDKs
      3. Offering CLIs for APIs
      4. Summary
    3. Chapter 12. API Testing Strategies
      1. Acceptance Testing
      2. Automated Security Testing
      3. Operational Monitoring
      4. API Contract Testing
      5. Selecting Tools to Accelerate Testing
      6. The Challenges of API Testing
      7. Make API Testing Essential
      8. Summary
    4. Chapter 13. Document the API Design
      1. The Importance of API Documentation
      2. API Description Formats
      3. Extending Docs with Code Examples
      4. From Reference Docs to a Developer Portal
      5. Effective API Documentation
      6. The Minimum Viable Portal
      7. Tools and Frameworks for Developer Portals
      8. Summary
    5. Chapter 14. Designing for Change
      1. The Impact of Change on Existing APIs
      2. API Versioning Strategies
      3. Deprecating APIs
      4. Establishing an API Stability Contract
      5. Summary
    6. Chapter 15. Protecting APIs
      1. The Potential for API Mischief
      2. Essential API Protection Practices
      3. Components of API Protection
      4. API Gateway Topologies
      5. Identity and Access Management
      6. Considerations before Building an In-House API Gateway
      7. Summary
    7. Chapter 16. Continuing the API Design Journey
      1. Establishing an API Style Guide
      2. Conducting API Design Reviews
      3. Developing a Culture of Reuse
      4. The Journey Has Only Begun
  19. Appendix: HTTP Primer
    1. Overview of HTTP
    2. The Uniform Resource Locator
    3. HTTP Request
    4. HTTP Response
    5. Common HTTP Methods
    6. HTTP Response Codes
    7. Content Negotiation
    8. Cache Control
    9. Conditional Requests
    10. Concurrency Control in HTTP
    11. Summary
  20. Index
  21. Code Snippets

Product information

  • Title: Principles of Web API Design: Delivering Value with APIs and Microservices
  • Author(s): James Higginbotham
  • Release date: December 2021
  • Publisher(s): Addison-Wesley Professional
  • ISBN: 9780137355754