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