Principles of Web ADI Design is a comprehensive, start-to-finish guide to the processes required for effective API design. Unlike other books, it covers the entire lifecycle. Leading API and microservices consultant James Higginbotham shows how API development teams can successfully integrate processes that occur before, during, and after API design, to scale API development far beyond single individuals or small teams. Higginbotham addresses REST in depth while also fully covering RPC and graph-based API design, as well as messaging, streaming, and event-based async APIs. Coverage includes

  • The art of API design, and an overview of the API design process

  • Crafting job stories, conducting EventStorming sessions, and modeling API capabilities

  • Designing APIs that can easily evolve

  • Implementing APIs, and moving to microservices

  • Improving API quality through effective testing, documentation, and protection mechanisms

  • Establishing and maturing your API program: leveraging program and data management techniques that scale

Table of Contents

  1. Cover Page
  2. Title Page
  3. Contents
  4. Table of Contents
  5. Preface
    1. Who Should Read This Book
    2. About This Book
    3. What’s Not in the Book
  6. About the Author
  7. I: Introduction to Web API Design
    1. 1. The Principles of API Design
    2. The Elements of Web API Design
    3. API Design Is Communication
    4. Reviewing the Principles of Software Design
    5. Resource-Based API Design
    6. The Principles of Web API Design
    7. Summary
    8. 2. Collaborative API Design
    9. Why an API Design Process?
    10. API Design Process Anti-Patterns
    11. The API Design-First Approach
    12. Remaining Agile with API Design-First
    13. The Align-Define-Design-Refine Process
    14. The Role of DDD in API Design
    15. API Design Involves Everyone
    16. Applying the Process Effectively
    17. Summary
  8. II: Aligning on API Outcomes
    1. 3. Identify Digital Capabilities
    2. Ensuring Stakeholder Alignment
    3. What are Digital Capabilities?
    4. Focusing on the Jobs to be Done
    5. What are Job Stories?
    6. The Components of a Job Story
    7. Writing Job Stories for APIs
    8. Overcoming Job Story Challenges
    9. Techniques for Capturing Job Stories
    10. A Real-World API Design Project
    11. Job Story Examples
    12. Summary
    13. 4. Capture Activities and Steps
    14. Extending Job Stories into Activities and Steps
    15. Using EventStorming for Collaborative Understanding
    16. How EventStorming Works
    17. The Benefits of EventStorming
    18. Facilitating an EventStorming Session
    19. Summary
  9. III: Defining Candidate APIs
    1. 5. Identifying API Boundaries
    2. Avoiding API Boundary Anti-Patterns
    3. Bounded Contexts, Subdomains, and APIs
    4. Finding API Boundaries Using EventStorming
    5. Finding API Boundaries Through Activities
    6. Naming and Scoping APIs
    7. Summary
    8. 6. API Modeling
    9. What is API Modeling?
    10. The API Modeling Process
    11. Validating the API Model with Sequence Diagrams
    12. Evaluating API Priority and Reuse
    13. Summary
  10. IV: Designing APIs
    1. 7. REST-Based API Design
    2. What is a REST-based API?
    3. REST API Design Process
    4. Selecting a Representation Format
    5. Common REST Design Patterns
    6. Summary
    7. 8. RPC and Query-Based API Design
    8. What is an RPC-based API?
    9. RPC API Design Process
    10. What is a Query-Based API?
    11. Query-Based API Design Process
    12. Summary
    13. 9. Async APIs for Eventing and Streaming
    14. The Problem with API Polling
    15. Async APIs Create New Possibilities
    16. A Review of Messaging Fundamentals
    17. Async API Styles
    18. Designing Async APIs
    19. Documenting Async APIs
    20. Summary
  11. V: Refining the API Design
    1. 10. From APIs to Microservices
    2. What Are Microservices?
    3. Microservices Reduce Coordination Costs
    4. The Difference Between APIs and Microservices
    5. Weighing the Complexity of Microservices
    6. Synchronous and Asynchronous Microservices
    7. Microservice Architecture Styles
    8. Right-Sizing Microservices
    9. Decomposing APIs Into Microservices
    10. Considerations When Transitioning to Microservices
    11. Summary
    12. 11. Improving the Developer Experience
    13. Creating a Mock API Implementation
    14. Providing Helper Libraries and SDKs
    15. Offering CLIs for APIs
    16. Summary
    17. 12. API Testing Strategies
    18. Acceptance Testing
    19. Automated Security Testing
    20. Operational Monitoring
    21. API Contract Testing
    22. Selecting Tools to Accelerate Testing
    23. The Challenges of API Testing
    24. Make API Testing Essential
    25. Summary
    26. 13. Document the API Design
    27. The Importance of API Documentation
    28. API Description Formats
    29. Extending Docs with Code Examples
    30. From Reference Docs to a Developer Portal
    31. Effective API Documentation
    32. The Minimum Viable Portal (MVP)
    33. Tools and Frameworks for Developer Portals
    34. Summary
    35. 14. Designing for Change
    36. The Impact of Change on Existing APIs
    37. API Versioning Strategies
    38. Deprecating APIs
    39. Establishing an API Stability Contract
    40. Summary
    41. 15. Protecting APIs
    42. The Potential for API Mischief
    43. Essential API Protection Practices
    44. Components of API Protection
    45. API Gateway Topologies
    46. Identity and Access Management (IAM)
    47. Considerations Before Building an In-House API Gateway
    48. Summary
    49. 16. Continuing the API Design Journey
    50. Establishing an API Style Guide
    51. Conducting API Design Reviews
    52. Developing a Culture of Reuse
    53. The Journey Has Only Begun
  12. Appendix A. HTTP Primer
    1. Overview of HTTP
    2. The Uniform Resource Locator (URL)
    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