API Design Patterns

API Design Patterns
brief contents
contents
foreword
preface
acknowledgments
about this book
	Who should read this book
	How this book is organized: A roadmap
	About the code
	Live book discussion forum
	Other online resources
about the author
about the cover illustration
Part 1—Introduction
	1 Introduction to APIs
		1.1 What are web APIs?
		1.2 Why do APIs matter?
		1.3 What are resource-oriented APIs?
		1.4 What makes an API “good”?
			1.4.1 Operational
			1.4.2 Expressive
			1.4.3 Simple
			1.4.4 Predictable
		Summary
	2 Introduction to API design patterns
		2.1 What are API design patterns?
		2.2 Why are API design patterns important?
		2.3 Anatomy of an API design pattern
			2.3.1 Name and synopsis
			2.3.2 Motivation
			2.3.3 Overview
			2.3.4 Implementation
			2.3.5 Trade-offs
		2.4 Case study: Twapi, a Twitter-like API
			2.4.1 Overview
			2.4.2 Listing messages
			2.4.3 Exporting data
		Summary
Part 2—Design principles
	3 Naming
		3.1 Why do names matter?
		3.2 What makes a name “good”?
			3.2.1 Expressive
			3.2.2 Simple
			3.2.3 Predictable
		3.3 Language, grammar, and syntax
			3.3.1 Language
			3.3.2 Grammar
			3.3.3 Syntax
		3.4 Context
		3.5 Data types and units
		3.6 Case study: What happens when you choose bad names?
		3.7 Exercises
		Summary
	4 Resource scope and hierarchy
		4.1 What is resource layout?
			4.1.1 Types of relationships
			4.1.2 Entity relationship diagrams
		4.2 Choosing the right relationship
			4.2.1 Do you need a relationship at all?
			4.2.2 References or in-line data
			4.2.3 Hierarchy
		4.3 Anti-patterns
			4.3.1 Resources for everything
			4.3.2 Deep hierarchies
			4.3.3 In-line everything
		4.4 Exercises
		Summary
	5 Data types and defaults
		5.1 Introduction to data types
			5.1.1 Missing vs. null
		5.2 Booleans
		5.3 Numbers
			5.3.1 Bounds
			5.3.2 Default values
			5.3.3 Serialization
		5.4 Strings
			5.4.1 Bounds
			5.4.2 Default values
			5.4.3 Serialization
		5.5 Enumerations
		5.6 Lists
			5.6.1 Atomicity
			5.6.2 Bounds
			5.6.3 Default values
		5.7 Maps
			5.7.1 Bounds
			5.7.2 Default values
		5.8 Exercises
		Summary
Part 3—Fundamentals
	6 Resource identification
		6.1 What is an identifier?
		6.2 What makes a good identifier?
			6.2.1 Easy to use
			6.2.2 Unique
			6.2.3 Permanent
			6.2.4 Fast and easy to generate
			6.2.5 Unpredictable
			6.2.6 Readable, shareable, and verifiable
			6.2.7 Informationally dense
		6.3 What does a good identifier look like?
			6.3.1 Data type
			6.3.2 Character set
			6.3.3 Identifier format
			6.3.4 Checksums
			6.3.5 Resource type
			6.3.6 Hierarchy and uniqueness scope
		6.4 Implementation
			6.4.1 Size
			6.4.2 Generation
			6.4.3 Tomb-stoning
			6.4.4 Checksum
			6.4.5 Database storage
		6.5 What about UUIDs?
		6.6 Exercises
		Summary
	7 Standard methods
		7.1 Motivation
		7.2 Overview
		7.3 Implementation
			7.3.1 Which methods should be supported?
			7.3.2 Idempotence and side effects
			7.3.3 Get
			7.3.4 List
			7.3.5 Create
			7.3.6 Update
			7.3.7 Delete
			7.3.8 Replace
			7.3.9 Final API definition
		7.4 Trade-offs
		7.5 Exercises
		Summary
	8 Partial updates and retrievals
		8.1 Motivation
			8.1.1 Partial retrieval
			8.1.2 Partial update
		8.2 Overview
		8.3 Implementation
			8.3.1 Transport
			8.3.2 Maps and nested interfaces
			8.3.3 Repeated fields
			8.3.4 Default values
			8.3.5 Implicit field masks
			8.3.6 Updating dynamic data structures
			8.3.7 Invalid fields
			8.3.8 Final API definition
		8.4 Trade-offs
			8.4.1 Universal support
			8.4.2 Alternative implementations
		8.5 Exercises
		Summary
	9 Custom methods
		9.1 Motivation
			9.1.1 Why not just standard methods?
		9.2 Overview
		9.3 Implementation
			9.3.1 Side effects
			9.3.2 Resources vs. collections
			9.3.3 Stateless custom methods
			9.3.4 Final API definition
		9.4 Trade-offs
		9.5 Exercises
		Summary
	10 Long-running operations
		10.1 Motivation
		10.2 Overview
		10.3 Implementation
			10.3.1 What does an LRO look like?
			10.3.2 Resource hierarchy
			10.3.3 Resolution
			10.3.4 Error handling
			10.3.5 Monitoring progress
			10.3.6 Canceling operations
			10.3.7 Pausing and resuming operations
			10.3.8 Exploring operations
			10.3.9 Persistence
			10.3.10 Final API definition
		10.4 Trade-offs
		10.5 Exercises
		Summary
	11 Rerunnable jobs
		11.1 Motivation
		11.2 Overview
		11.3 Implementation
			11.3.1 Job resources
			11.3.2 The custom run method
			11.3.3 Job execution resources
			11.3.4 Final API definition
		11.4 Trade-offs
		11.5 Exercises
		Summary
Part 4—Resource relationships
	12 Singleton sub-resources
		12.1 Motivation
			12.1.1 Why should we use a singleton sub-resource?
		12.2 Overview
		12.3 Implementation
			12.3.1 Standard methods
			12.3.2 Resetting
			12.3.3 Hierarchy
			12.3.4 Final API definition
		12.4 Trade-offs
			12.4.1 Atomicity
			12.4.2 Exactly one sub-resource
		12.5 Exercises
		Summary
	13 Cross references
		13.1 Motivation
		13.2 Overview
		13.3 Implementation
			13.3.1 Reference field name
			13.3.2 Data integrity
			13.3.3 Value vs. reference
			13.3.4 Final API definition
		13.4 Trade-offs
		13.5 Exercises
		Summary
	14 Association resources
		14.1 Motivation
		14.2 Overview
			14.2.1 Association alias methods
		14.3 Implementation
			14.3.1 Naming the association resource
			14.3.2 Standard method behavior
			14.3.3 Uniqueness
			14.3.4 Read-only fields
			14.3.5 Association alias methods
			14.3.6 Referential integrity
			14.3.7 Final API definition
		14.4 Trade-offs
			14.4.1 Complexity
			14.4.2 Separation of associations
		14.5 Exercises
		Summary
	15 Add and remove custom methods
		15.1 Motivation
		15.2 Overview
		15.3 Implementation
			15.3.1 Listing associated resources
			15.3.2 Data integrity
			15.3.3 Final API definition
		15.4 Trade-offs
			15.4.1 Nonreciprocal relationship
			15.4.2 Relationship metadata
		15.5 Exercises
		Summary
	16 Polymorphism
		16.1 Motivation
		16.2 Overview
		16.3 Implementation
			16.3.1 Deciding when to use polymorphic resources
			16.3.2 Polymorphic structure
			16.3.3 Polymorphic behavior
			16.3.4 Why not polymorphic methods?
			16.3.5 Final API definition
		16.4 Trade-offs
		16.5 Exercises
		Summary
Part 5—Collective operations
	17 Copy and move
		17.1 Motivation
		17.2 Overview
		17.3 Implementation
			17.3.1 Identifiers
			17.3.2 Child resources
			17.3.3 Related resources
			17.3.4 External data
			17.3.5 Inherited metadata
			17.3.6 Atomicity
			17.3.7 Final API definition
		17.4 Trade-offs
		17.5 Exercises
		Summary
	18 Batch operations
		18.1 Motivation
		18.2 Overview
		18.3 Implementation
			18.3.1 Atomicity
			18.3.2 Operation on the collection
			18.3.3 Ordering of results
			18.3.4 Common fields
			18.3.5 Operating across parents
			18.3.6 Batch Get
			18.3.7 Batch Delete
			18.3.8 Batch Create
			18.3.9 Batch Update
			18.3.10 Final API definition
		18.4 Trade-offs
		18.5 Exercises
		Summary
	19 Criteria-based deletion
		19.1 Motivation
		19.2 Overview
		19.3 Implementation
			19.3.1 Filtering results
			19.3.2 Validation only by default
			19.3.3 Result count
			19.3.4 Result sample set
			19.3.5 Consistency
			19.3.6 Final API definition
		19.4 Trade-offs
		19.5 Exercises
		Summary
	20 Anonymous writes
		20.1 Motivation
		20.2 Overview
		20.3 Implementation
			20.3.1 Consistency
			20.3.2 Final API definition
		20.4 Trade-offs
		20.5 Exercises
		Summary
	21 Pagination
		21.1 Motivation
		21.2 Overview
		21.3 Implementation
			21.3.1 Page size
			21.3.2 Page tokens
			21.3.3 Total count
			21.3.4 Paging inside resources
			21.3.5 Final API definition
		21.4 Trade-offs
			21.4.1 Bi-directional paging
			21.4.2 Arbitrary windows
		21.5 Anti-pattern: Offsets and limits
		21.6 Exercises
		Summary
	22 Filtering
		22.1 Motivation
		22.2 Overview
		22.3 Implementation
			22.3.1 Structure
			22.3.2 Filter syntax and behavior
			22.3.3 Final API definition
		22.4 Trade-offs
		22.5 Exercises
		Summary
	23 Importing and exporting
		23.1 Motivation
		23.2 Overview
		23.3 Implementation
			23.3.1 Import and export methods
			23.3.2 Interacting with storage systems
			23.3.3 Converting between resources and bytes
			23.3.4 Consistency
			23.3.5 Identifiers and collisions
			23.3.6 Handling related resources
			23.3.7 Failures and retries
			23.3.8 Filtering and field masks
			23.3.9 Final API definition
		23.4 Trade-offs
		23.5 Exercises
		Summary
Part 6—Safety and security
	24 Versioning and compatibility
		24.1 Motivation
		24.2 Overview
			24.2.1 What is compatibility?
			24.2.2 Defining backward compatibility
		24.3 Implementation
			24.3.1 Perpetual stability
			24.3.2 Agile instability
			24.3.3 Semantic versioning
		24.4 Trade-offs
			24.4.1 Granularity vs. simplicity
			24.4.2 Stability vs. new functionality
			24.4.3 Happiness vs. ubiquity
		24.5 Exercises
		Summary
	25 Soft deletion
		25.1 Motivation
		25.2 Overview
		25.3 Implementation
			25.3.1 Deleted designation
			25.3.2 Modifying standard methods
			25.3.3 Undeleting
			25.3.4 Expunging
			25.3.5 Expiration
			25.3.6 Referential integrity
			25.3.7 Effects on other methods
			25.3.8 Adding soft delete across versions
			25.3.9 Final API definition
		25.4 Trade-offs
		25.5 Exercises
		Summary
	26 Request deduplication
		26.1 Motivation
		26.2 Overview
		26.3 Implementation
			26.3.1 Request identifier
			26.3.2 Response caching
			26.3.3 Consistency
			26.3.4 Request ID collisions
			26.3.5 Cache expiration
			26.3.6 Final API definition
		26.4 Trade-offs
		26.5 Exercises
		Summary
	27 Request validation
		27.1 Motivation
		27.2 Overview
		27.3 Implementation
			27.3.1 External dependencies
			27.3.2 Special side effects
			27.3.3 Final API definition
		27.4 Trade-offs
		27.5 Exercises
		Summary
	28 Resource revisions
		28.1 Motivation
		28.2 Overview
		28.3 Implementation
			28.3.1 Revision identifiers
			28.3.2 Creating revisions
			28.3.3 Retrieving specific revisions
			28.3.4 Listing revisions
			28.3.5 Restoring a previous revision
			28.3.6 Deleting revisions
			28.3.7 Handling child resources
			28.3.8 Final API definition
		28.4 Trade-offs
		28.5 Exercises
		Summary
	29 Request retrial
		29.1 Motivation
		29.2 Overview
			29.2.1 Client-side retry timing
			29.2.2 Server-specified retry timing
		29.3 Implementation
			29.3.1 Retry eligibility
			29.3.2 Exponential back-off
			29.3.3 Retry After
			29.3.4 Final API definition
		29.4 Trade-offs
		29.5 Exercises
		Summary
	30 Request authentication
		30.1 Motivation
			30.1.1 Origin
			30.1.2 Integrity
			30.1.3 Nonrepudiation
		30.2 Overview
		30.3 Implementation
			30.3.1 Credential generation
			30.3.2 Registration and credential exchange
			30.3.3 Generating and verifying raw signatures
			30.3.4 Request fingerprinting
			30.3.5 Including the signature
			30.3.6 Authenticating requests
			30.3.7 Final API definition
		30.4 Trade-offs
		30.5 Exercises
		Summary
index
	Numerics
	A
	B
	C
	D
	E
	F
	G
	H
	I
	J
	K
	L
	M
	N
	O
	P
	R
	S
	T
	U
	V
	W
	Z