Mastering API Architecture

Mastering API Architecture

by James Gough, Daniel Bryant, Matthew Auburn
Released October 2022
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781492090632

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.

Buy on Amazon Buy on ebooks.com
Start your free trial

Book description

Most organizations with a web presence build and operate APIs; the doorway for customers to interact with the company's services. Designing, building, and managing these critical programs affect everyone in the organization, from engineers and product owners to C-suite executives. But the real challenge for developers and solution architects is creating an API platform from the ground up.

With this practical book, you'll learn strategies for building and testing REST APIs that use API gateways to combine offerings at the microservice level. Authors James Gough, Daniel Bryant, and Matthew Auburn demonstrate how simple additions to this infrastructure can help engineers and organizations migrate to the cloud; and open the opportunity to connect internal services using technologies like a service mesh.

  • Learn API fundamentals and architectural patterns for building an API platform
  • Use practical examples to understand how to design, build, and test API-based systems
  • Deploy, operate, and configure key components of an API platform
  • Use API gateways and service meshes appropriately, based on case studies
  • Understand core security and common vulnerabilities in API architecture
  • Secure data and APIs using threat modeling and technologies like OAuth2 and TLS
  • Learn how to evolve existing systems toward API- and cloud-based architectures

Publisher resources

View/Submit Errata

Table of contents

  1. Foreword
  2. Preface
    1. Why Did We Write This Book?
    2. Why Should You Read This Book?
    3. Who This Book Is For
      1. Developer
      2. Accidental Architect
      3. Solutions/Enterprise Architect
    4. What You Will Learn
    5. What This Book Is Not
    6. Conventions Used in This Book
    7. Using Code Examples
    8. O’Reilly Online Learning
    9. How to Contact Us
    10. Acknowledgments
      1. James Gough
      2. Daniel Bryant
      3. Matthew Auburn
  3. Introduction
    1. The Architecture Journey
    2. A Brief Introduction to APIs
    3. Running Example: Conference System Case Study
      1. Types of APIs in the Conference Case Study
      2. Reasons for Changing the Conference System
      3. From Tiered Architecture to Modeling APIs
      4. Case Study: An Evolutionary Step
      5. API Infrastructure and Traffic Patterns
      6. Roadmap for the Conference Case Study
    4. Using C4 Diagrams
      1. C4 Context Diagram
      2. C4 Container Diagram
      3. C4 Component Diagram
    5. Using Architecture Decision Records
      1. Attendees Evolution ADR
      2. Mastering API: ADR Guidelines
    6. Summary
  4. I. Designing, Building, and Testing APIs
  5. 1. Design, Build, and Specify APIs
    1. Case Study: Designing the Attendee API
    2. Introduction to REST
      1. Introduction to REST and HTTP by Example
      2. The Richardson Maturity Model
    3. Introduction to Remote Procedure Call (RPC) APIs
    4. A Brief Mention of GraphQL
    5. REST API Standards and Structure
      1. Collections and Pagination
      2. Filtering Collections
      3. Error Handling
      4. ADR Guideline: Choosing an API Standard
    6. Specifying REST APIs Using OpenAPI
    7. Practical Application of OpenAPI Specifications
      1. Code Generation
      2. OpenAPI Validation
      3. Examples and Mocking
      4. Detecting Changes
    8. API Versioning
      1. Semantic Versioning
      2. OpenAPI Specification and Versioning
    9. Implementing RPC with gRPC
    10. Modeling Exchanges and Choosing an API Format
      1. High-Traffic Services
      2. Large Exchange Payloads
      3. HTTP/2 Performance Benefits
      4. Vintage Formats
    11. Guideline: Modeling Exchanges
    12. Multiple Specifications
      1. Does the Golden Specification Exist?
      2. Challenges of Combined Specifications
    13. Summary
  6. 2. Testing APIs
    1. Conference System Scenario for This Chapter
    2. Testing Strategies
      1. Test Quadrant
      2. Test Pyramid
      3. ADR Guideline for Testing Strategies
    3. Contract Testing
      1. Why Contract Testing Is Often Preferable
      2. How a Contract Is Implemented
      3. ADR Guideline: Contract Testing
    4. API Component Testing
      1. Contract Testing Versus Component Testing
      2. Case Study: Component Test to Verify Behavior
    5. API Integration Testing
      1. Using Stub Servers: Why and How
      2. ADR Guideline: Integration Testing
      3. Containerizing Test Components: Testcontainers
      4. Case Study: Applying Testcontainers to Verify Integrations
    6. End-to-End Testing
      1. Automating End-to-End Validation
      2. Types of End-to-End Tests
      3. ADR Guideline: End-to-End Testing
    7. Summary
  7. II. API Traffic Management
  8. 3. API Gateways: Ingress Traffic Management
    1. Is an API Gateway the Only Solution?
    2. Guideline: Proxy, Load Balancer, or API Gateway
    3. Case Study: Exposing the Attendee Service to Consumers
    4. What Is an API Gateway?
    5. What Functionality Does an API Gateway Provide?
    6. Where Is an API Gateway Deployed?
    7. How Does an API Gateway Integrate with Other Technologies at the Edge?
    8. Why Use an API Gateway?
      1. Reduce Coupling: Adapter/Facade Between Frontends and Backends
      2. Simplify Consumption: Aggregating/Translating Backend Services
      3. Protect APIs from Overuse and Abuse: Threat Detection and Mitigation
      4. Understand How APIs Are Being Consumed: Observability
      5. Manage APIs as Products: API Lifecycle Management
      6. Monetize APIs: Account Management, Billing, and Payment
    9. A Modern History of API Gateways
      1. 1990s Onward: Hardware Load Balancers
      2. Early 2000s Onward: Software Load Balancers
      3. Mid-2000s: Application Delivery Controllers (ADCs)
      4. Early 2010s: First-Generation API Gateways
      5. 2015 Onward: Second-Generation API Gateways
    10. Current API Gateway Taxonomy
      1. Traditional Enterprise Gateways
      2. Microservices/Micro Gateways
      3. Service Mesh Gateways
      4. Comparing API Gateway Types
    11. Case Study: Evolving the Conference System Using an API Gateway
      1. Installing Ambassador Edge Stack in Kubernetes
      2. Configuring Mappings from URL Paths to Backend Services
      3. Configuring Mappings Using Host-based Routing
    12. Deploying API Gateways: Understanding and Managing Failure
      1. API Gateway as a Single Point of Failure
      2. Detecting and Owning Problems
      3. Resolving Incidents and Issues
      4. Mitigating Risks
    13. Common API Gateway Implementation Pitfalls
      1. API Gateway Loopback
      2. API Gateway as an ESB
      3. Turtles (API Gateways) All the Way Down
    14. Selecting an API Gateway
      1. Identifying Requirements
      2. Build Versus Buy
      3. ADR Guideline: Selecting an API Gateway
    15. Summary
  9. 4. Service Mesh: Service-to-Service Traffic Management
    1. Is Service Mesh the Only Solution?
    2. Guideline: Should You Adopt Service Mesh?
    3. Case Study: Extracting Sessions Functionality to a Service
    4. What Is Service Mesh?
    5. What Functionality Does a Service Mesh Provide?
    6. Where Is a Service Mesh Deployed?
    7. How Does a Service Mesh Integrate with Other Networking Technologies?
    8. Why Use a Service Mesh?
      1. Fine-grained Control of Routing, Reliability, and Traffic Management
      2. Provide Transparent Observability
      3. Enforce Security: Transport Security, Authentication, and Authorization
      4. Supporting Cross-Functional Communication Across Languages
      5. Separating Ingress and Service-to-Service Traffic Management
    9. Evolution of Service Mesh
      1. Early History and Motivations
      2. Implementation Patterns
    10. Service Mesh Taxonomy
    11. Case Study: Using a Service Mesh for Routing, Observability, and Security
      1. Routing with Istio
      2. Observing Traffic with Linkerd
      3. Network Segmentation with Consul
    12. Deploying a Service Mesh: Understanding and Managing Failure
      1. Service Mesh as a Single Point of Failure
    13. Common Service Mesh Implementation Challenges
      1. Service Mesh as ESB
      2. Service Mesh as Gateway
      3. Too Many Networking Layers
    14. Selecting a Service Mesh
      1. Identifying Requirements
      2. Build Versus Buy
      3. Checklist: Selecting a Service Mesh
    15. Summary
  10. III. API Operations and Security
  11. 5. Deploying and Releasing APIs
    1. Separating Deployment and Release
      1. Case Study: Feature Flagging
      2. Traffic Management
    2. Case Study: Modeling Releases in the Conference System
      1. API Lifecycle
      2. Mapping Release Strategies to Lifecycle
      3. ADR Guideline: Separating Release from Deployment with Traffic Management and Feature Flags
    3. Release Strategies
      1. Canary Releases
      2. Traffic Mirroring
      3. Blue-Green
    4. Case Study: Performing Rollouts with Argo Rollouts
    5. Monitoring for Success and Identifying Failure
      1. Three Pillars of Observability
      2. Important Metrics for APIs
      3. Reading the Signals
    6. Application Decisions for Effective Software Releases
      1. Response Caching
      2. Application-Level Header Propagation
      3. Logging to Assist Debugging
      4. Considering an Opinionated Platform
      5. ADR Guideline: Opinionated Platforms
    7. Summary
  12. 6. Operational Security: Threat Modeling for APIs
    1. Case Study: Applying OWASP to the Attendee API
    2. The Risk of Not Securing External APIs
    3. Threat Modeling 101
    4. Thinking Like an Attacker
    5. How to Threat Model
      1. Step 1: Identify Your Objectives
      2. Step 2: Gather the Right Information
      3. Step 3: Decompose the System
      4. Step 4: Identify Threats—Taking This in Your STRIDE
      5. Step 5: Evaluate Threat Risks
      6. Step 6: Validation
    6. Summary
  13. 7. API Authentication and Authorization
    1. Authentication
      1. End-User Authentication with Tokens
      2. System-to-System Authentication
      3. Why You Shouldn’t Mix Keys and Users
    2. OAuth2
      1. Authorization Server Role with API Interactions
      2. JSON Web Tokens (JWT)
      3. Terminology and Mechanisms of OAuth2 Grants
      4. ADR Guideline: Should I Consider Using OAuth2?
      5. Authorization Code Grant
      6. Refresh Tokens
      7. Client Credentials Grant
      8. Additional OAuth2 Grants
      9. ADR Guideline: Choosing Which OAuth2 Grants to Support
      10. OAuth2 Scopes
      11. Authorization Enforcement
    3. Introducing OIDC
    4. SAML 2.0
    5. Summary
  14. IV. Evolutionary Architecture with APIs
  15. 8. Redesigning Applications to API-Driven Architectures
    1. Why Use APIs to Evolve a System?
      1. Creating Useful Abstractions: Increasing Cohesion
      2. Clarifying Domain Boundaries: Promoting Loose Coupling
    2. Case Study: Establishing Attendee Domain Boundaries
    3. End State Architecture Options
      1. Monolith
      2. Service-Oriented Architecture (SOA)
      3. Microservices
      4. Functions
    4. Managing the Evolutionary Process
      1. Determine Your Goals
      2. Using Fitness Functions
      3. Decomposing a System into Modules
      4. Creating APIs as “Seams” for Extension
      5. Identifying Change Leverage Points within a System
      6. Continuous Delivery and Verification
    5. Architectural Patterns for Evolving Systems with APIs
      1. Strangler Fig
      2. Facade and Adapter
      3. API Layer Cake
    6. Identifying Pain Points and Opportunities
      1. Upgrade and Maintenance Issues
      2. Performance Issues
      3. Breaking Dependencies: Highly Coupled APIs
    7. Summary
  16. 9. Using API Infrastructure to Evolve Toward Cloud Platforms
    1. Case Study: Moving the Attendee Service to the Cloud
    2. Choosing a Cloud Migration Strategy
      1. Retain or Revisit
      2. Rehost
      3. Replatform
      4. Repurchase
      5. Refactor/Re-architect
      6. Retire
    3. Case Study: Replatforming the Attendee Service to the Cloud
    4. Role of API Management
    5. North–South Versus East–West: Blurring Lines of Traffic Management
      1. Start at the Edge and Work Inward
      2. Crossing Boundaries: Routing Across Networks
    6. From Zonal Architecture to Zero Trust
      1. Getting in the Zone
      2. Trust No One and Verify
      3. Role of Service Mesh in Zero Trust Architectures
    7. Summary
  17. 10. Wrap-up
    1. Case Study: A Look Back on Your Journey
    2. APIs, Conway’s Law, and Your Organization
    3. Understanding Decision Types
    4. Preparing for the Future
      1. Async Communication
      2. HTTP/3
      3. Platform-based Mesh
    5. What’s Next: How to Keep Learning About API Architecture
      1. Continually Honing the Fundamentals
      2. Keeping Up-to-Date with Industry News
      3. Radars, Quadrants, and Trend Reports
      4. Learning About Best Practices and Use Cases
      5. Learning by Doing
      6. Learning by Teaching
  18. Index
  19. About the Authors

Product information

  • Title: Mastering API Architecture
  • Author(s): James Gough, Daniel Bryant, Matthew Auburn
  • Release date: October 2022
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781492090632