Principles of Web API Design: Delivering Value with APIs and Microservices (Addison-Wesley Signature Series (Vernon))

Cover
Half Title
Title Page
Copyright Page
Contents
Series Editor Foreword
Foreword
Preface
Acknowledgments
About the Author
Part I: Introduction to Web API Design
	Chapter 1: The Principles of API Design
		The Elements of Web API Design
			Business Capabilities
			Product Thinking
			Developer Experience
		API Design Is Communication
		Reviewing the Principles of Software Design
			Modularization
			Encapsulation
			High Cohesion and Loose Coupling
		Resource-Based API Design
			Resources Are Not Data Models
		Resources Are Not Object or Domain Models
		Resource-Based APIs Exchange Messages
		The Principles of Web API Design
		Summary
	Chapter 2: Collaborative API Design
		Why an API Design Process?
		API Design Process Antipatterns
			The Leaky Abstraction Antipattern
			The Next Release Design Fix Antipattern
			The Heroic Design Effort Antipattern
			The Unused API Antipattern
		The API Design-First Approach
		Remaining Agile with API Design-First
			The Agile Manifesto Revisited
			The Agility of API Design-First
		The Align-Define-Design-Refine Process
		The Role of DDD in API Design
		API Design Involves Everyone
		Applying the Process Effectively
		Summary
Part II: Aligning on API Outcomes
	Chapter 3: Identify Digital Capabilities
		Ensuring Stakeholder Alignment
		What Are Digital Capabilities?
		Focusing on the Jobs to Be Done
		What Are Job Stories?
		The Components of a Job Story
		Writing Job Stories for APIs
			Method 1: When the Problem Is Known
			Method 2: When the Desired Outcome Is Known
			Method 3: When the Digital Capability Has Been Identified
		Overcoming Job Story Challenges
			Challenge 1: Job Stories Are Too Detailed
			Challenge 2: Job Stories Are Feature Centric
			Challenge 3: Additional User Context Is Needed
		Techniques for Capturing Job Stories
		A Real-World API Design Project
		Job Story Examples
		Summary
	Chapter 4: Capture Activities and Steps
		Extending Job Stories into Activities and Steps
			Identify the Activities for Each Job Story
			Decompose Each Activity into Steps
			What If Requirements Aren’t Clear?
		Using EventStorming for Collaborative Understanding
		How EventStorming Works
			Step 1: Identify Business Domain Events
			Step 2: Create an Event Narrative
			Step 3: Review the Narrative and Identify Gaps
			Step 4: Expand Domain Understanding
			Step 5: Review the Final Narrative
		The Benefits of EventStorming
			Who Should Be Involved?
		Facilitating an EventStorming Session
			Prepare: Gathering Necessary Supplies
			Share: Communicating the EventStorming Session
			Execute: Conducting the EventStorming Session
			Wrap-up: Capture Activities and Activity Steps
			Follow-up: Post-Session Recommendations
			Customizing the Process
		Summary
Part III: Defining Candidate APIs
	Chapter 5: Identifying API Boundaries
		Avoiding API Boundary Antipatterns
			The Mega All-in-One API Antipattern
			The Overloaded API Antipattern
			The Helper API Antipattern
		Bounded Contexts, Subdomains, and APIs
		Finding API Boundaries Using EventStorming
		Finding API Boundaries through Activities
		Naming and Scoping APIs
		Summary
	Chapter 6: API Modeling
		What Is API Modeling?
			The API Profile Structure
		The API Modeling Process
			Step 1: Capture API Profile Summary
			Step 2: Identify the Resources
			Step 3: Define the Resource Taxonomy
			Step 4: Add Operation Events
			Step 5: Expand Operation Details
		Validating the API Model with Sequence Diagrams
		Evaluating API Priority and Reuse
		Summary
Part IV: Designing APIs
	Chapter 7: REST-Based API Design
		What Is a REST-Based API?
			REST Is Client/Server
			REST Is Resource-Centric
			REST Is Message Based
			REST Supports a Layered System
			REST Supports Code on Demand
			Hypermedia Controls
			When to Choose REST
		REST API Design Process
			Step 1: Design Resource URL Paths
			Step 2: Map API Operations to HTTP Methods
			Step 3: Assign Response Codes
			Step 4: Documenting the REST API Design
			Step 5: Share and Gather Feedback
		Selecting a Representation Format
			Resource Serialization
			Hypermedia Serialization
			Hypermedia Messaging
			Semantic Hypermedia Messaging
		Common REST Design Patterns
			Create-Read-Update-Delete
			Extended Resource Lifecycle Support
			Singleton Resources
			Background (Queued) Jobs
			Long-Running Transaction Support in REST
		Summary
	Chapter 8: RPC and Query-Based API Design
		What Is an RPC-Based API?
			The gRPC Protocol
			Factors When Considering RPC
		RPC API Design Process
			Step 1: Identify RPC Operations
			Step 2: Detail RPC Operations
			Step 3: Document the API Design
		What Is a Query-Based API?
			Understanding OData
			Exploring GraphQL
		Query-Based API Design Process
			Step 1: Designing Resource and Graph Structures
			Step 2: Design Query and Mutation Operations
			Step 3: Document the API Design
		Summary
	Chapter 9: Async APIs for Eventing and Streaming
		The Problem with API Polling
		Async APIs Create New Possibilities
		A Review of Messaging Fundamentals
			Messaging Styles and Locality
			The Elements of a Message
			Understanding Messaging Brokers
			Point-to-Point Message Distribution (Queues)
			Fanout Message Distribution (Topics)
			Message Streaming Fundamentals
		Async API Styles
			Server Notification Using Webhooks
			Server Push Using Server-Sent Events
			Bidirectional Notification via WebSocket
			gRPC Streaming
			Selecting an Async API Style
		Designing Async APIs
			Command Messages
			Event Notifications
			Event-Carried State Transfer Events
			Event Batching
			Event Ordering
			Documenting Async APIs
		Summary
Part V: Refining the API Design
	Chapter 10: From APIs to Microservices
		What Are Microservices?
		Microservices Reduce Coordination Costs
		The Difference between APIs and Microservices
		Weighing the Complexity of Microservices
			Self-Service Infrastructure
			Independent Release Cycles
			Shift to Single-Team Ownership
			Organizational Structure and Cultural Impacts
			Shift in Data Ownership
			Distributed Data Management and Governance
			Distributed Systems Challenges
			Resiliency, Failover, and Distributed Transactions
			Refactoring and Code Sharing Challenges
		Synchronous and Asynchronous Microservices
		Microservice Architecture Styles
			Direct Service Communication
			API-Based Orchestration
			Cell-Based Architecture
		Right-Sizing Microservices
		Decomposing APIs into Microservices
			Step 1: Identify Candidate Microservices
			Step 2: Add Microservices into API Sequence Diagrams
			Step 3: Capture Using the Microservice Design Canvas
			Additional Microservice Design Considerations
		Considerations When Transitioning to Microservices
		Summary
	Chapter 11: Improving the Developer Experience
		Creating a Mock API Implementation
			Static API Mocking
			API Prototype Mocking
			README-Based Mocking
		Providing Helper Libraries and SDKs
			Options for Offering Helper Libraries
			Versioning Helper Libraries
			Helper Library Documentation and Testing
		Offering CLIs for APIs
		Summary
	Chapter 12: API Testing Strategies
		Acceptance Testing
		Automated Security Testing
		Operational Monitoring
		API Contract Testing
		Selecting Tools to Accelerate Testing
		The Challenges of API Testing
		Make API Testing Essential
		Summary
	Chapter 13: Document the API Design
		The Importance of API Documentation
		API Description Formats
			OpenAPI Specification
			API Blueprint
			RAML
			JSON Schema
			API Profiles Using ALPS
			Improving API Discovery Using APIs.json
		Extending Docs with Code Examples
			Write Getting Started Code Examples First
			Expanding Documentation with Workflow Examples
			Error Case and Production-Ready Examples
		From Reference Docs to a Developer Portal
			Increasing API Adoption through Developer Portals
			Elements of a Great Developer Portal
		Effective API Documentation
			Question 1: How Does Your API Solve My Problems?
			Question 2: What Problem Does Each API Operation Support?
			Question 3: How Do I Get Started Using the API?
			The Role of Technical Writer in API Docs
		The Minimum Viable Portal
			Phase 1: Minimum Viable Portal
			Phase 2: Improvement
			Phase 3: Focusing on Growth
		Tools and Frameworks for Developer Portals
		Summary
	Chapter 14: Designing for Change
		The Impact of Change on Existing APIs
			Perform an API Design Gap Analysis
			Determine What Is Best for API Consumers
			Change Management Is Built on Trust
			Strategies for Change
		API Versioning Strategies
			Common Nonbreaking Changes
			Incompatible Changes
			API Versions and Revisions
			API Versioning Methods
			Business Considerations of API Versioning
		Deprecating APIs
			Establish a Deprecation Policy
			Announcing a Deprecation
		Establishing an API Stability Contract
		Summary
	Chapter 15: Protecting APIs
		The Potential for API Mischief
		Essential API Protection Practices
		Components of API Protection
			API Gateways
			API Management
			Service Meshes
			Web Application Firewalls
			Content Delivery Networks
			Intelligent API Protection
		API Gateway Topologies
			API Management Hosting Options
			API Network Traffic Considerations
			Topology 1: API Gateway Direct to API Server
			Topology 2: API Gateway Routing to Services
			Topology 3: Multiple API Gateway Instances
		Identity and Access Management
			Passwords and API Keys
			API Tokens
			Pass-by-Reference versus Pass-by-Value API Tokens
			OAuth 2.0 and OpenID Connect
		Considerations before Building an In-House API Gateway
			Reason 1: API Security Is a Moving Target
			Reason 2: It Will Take Longer than Expected
			Reason 3: Expected Performance Takes Time
			What about Helper Libraries?
		Summary
	Chapter 16: Continuing the API Design Journey
		Establishing an API Style Guide
			Methods for Encouraging Style Guide Adherence
			Selecting Style Guide Tone
			Tips for Getting Started with an API Style Guide
			Supporting Multiple API Styles
		Conducting API Design Reviews
			Start with a Documentation Review
			Check for Standards and Design Consistency
			Review Automated Test Coverage
			Add Try It Out Support
		Developing a Culture of Reuse
		The Journey Has Only Begun
Appendix: HTTP Primer
Index
	A
	B
	C
	D
	E
	F
	G
	H
	I
	J
	K
	L
	M
	N
	O
	P
	Q
	R
	S
	T
	U
	V
	W
	X
	Y
	Z