Primary source
Book Cube: API Design Patterns
The original post used as the basis for this chapter.
API Design Patterns
Authors: JJ Geewax
Publisher: Manning Publications, 2021
Length: 480 pages
JJ Geewax's book on resource-oriented API design: contract patterns, change evolution, governance, and AIP practices.
Why this book matters for API governance
The book complements API Governance at Scale and AIP practices: instead of abstract guidance, it provides repeatable patterns you can turn into an operating governance model.
Author and context
JJ Geewax contributed to API governance practices at Google, helped shape AIP, and co-founded aip.dev.
Book focus
The book explains resource-oriented API design in a structured way: entities, actions, errors, and contract evolution.
Practical value
Useful for platform and product teams that want to reduce API sprawl and move toward engineering excellence.
What is inside the book: content map
1) Foundation: API as product and contract
The book starts with contract discipline rather than protocol details: why teams need a shared resource language and how to treat APIs as long-lived interfaces.
- Contract as product: consumers, boundaries, and fitness criteria.
- Resource-oriented modeling over endpoint-by-endpoint design.
- Naming and URI patterns as a way to lower cognitive load.
2) Operations and behavior
The next part explains how to keep operations predictable: what should be standard by default and when custom actions are justified.
- Standard methods (List/Get/Create/Update/Delete) and consistent semantics.
- Long-running operations, async processes, and status handling.
- Idempotency, retry safety, and side-effect control.
3) API evolution and compatibility
A central section focuses on changing contracts without breaking clients: field evolution, deprecation, and migration rules.
- Backwards-compatible change as the default strategy.
- Deprecation policy: announce, measure, and retire legacy safely.
- Breaking-change criteria and versioning guardrails.
4) Governance and organizational scaling
Final chapters move from team-level patterns to organization-level execution via standards, review workflows, and automation.
- Where style guides end and governance operating models begin.
- Policy-as-code checks in CI/CD and quality gates.
- Ownership roles, API reviews, and API catalog governance.
Core ideas from the book
A unified resource model beats one-off endpoint convenience
Locally optimized APIs quickly become a fragmented contract landscape. A resource model keeps behavior predictable across domains and teams.
Practical application: Define consistent collection/resource naming, identifier invariants, and parent-child hierarchy rules.
Method semantics must stay stable across the platform
If Create means upsert in one service and strict insert in another, clients become brittle and expensive to maintain.
Practical application: Set platform-level invariants for List/Get/Create/Update/Delete and enforce deviations via design review.
Idempotency and standardized errors improve both DX and reliability
Retries, timeouts, and duplicate calls are unavoidable. Without consistent error contracts, client retry logic degrades fast.
Practical application: Adopt requestId/idempotency keys for critical writes and use machine-readable structured error payloads.
API evolution must be a process, not ad-hoc exceptions
Most API failures appear on the second and tenth change, not on release day. Teams need lifecycle discipline and migration policy.
Practical application: Introduce change proposals, compatibility rules, and explicit deprecation windows for API consumers.
Governance scales only with automation
Manual review alone becomes a bottleneck. The book’s pattern catalog can be translated into enforceable policy checks.
Practical application: Run contract linting, breaking-change detection, and mandatory API quality gates in CI.
Ownership and API catalog hygiene are part of API design
Without clear owners and catalog visibility, even well-designed contracts degrade after team rotations.
Practical application: Maintain an API catalog with owner, maturity status, changelog, and links to specs and decision records.
Frequently reused patterns
Standard methods first
Problem: Each team invents its own verbs and lifecycle behavior.
Why it matters: Reduces variability, simplifies SDKs, and speeds up client integration.
Idempotent write operations
Problem: Retries create duplicates or inconsistent state after transient failures.
Why it matters: Enables safe retries and predictable behavior under network instability.
Long-running operation contract
Problem: Heavy workloads block synchronous flows and degrade API UX.
Why it matters: Separates operation start from result retrieval via explicit status semantics.
Governed deprecation lifecycle
Problem: Legacy fields never die and migration plans drift.
Why it matters: Allows teams to retire technical debt safely and plan consumer migrations.
Whitepaper
API Governance at Scale
Context on API decision-making and governance at scale.
How to implement these ideas in a real organization
Weeks 1-2: baseline standards
Create a minimal style guide for resource modeling, naming conventions, required error shape, and idempotency rules.
Weeks 3-4: API review workflow
Introduce lightweight review for new/changed contracts and a design decision template for non-trivial trade-offs.
Weeks 5-8: automation
Add compatibility checks and contract linting in CI/CD so policy is enforceable by default.
Weeks 9-10: catalog and ownership
Launch an API catalog with clear owners, maturity status, change history, and team/domain mapping.
Weeks 11-12: governance metrics
Track breaking-change rate, migration rollout speed, and first-pass policy gate success across teams.
What to do immediately after reading
- Audit 2-3 critical APIs for consistency in methods, errors, and idempotency behavior.
- Pick 5-7 mandatory rules that can be validated automatically, not only in manual reviews.
- Align teams on a deprecation notice format and migration calendar.
- Assign explicit API owners and publish owner-level SLA for contract evolution decisions.
Who should read it first
- Platform/API Guild members and architects building organization-wide standards.
- Microservice team leads with a growing set of internal and external APIs.
- Engineers preparing for senior/staff roles with an architecture quality focus.
Related chapters
- Continuous API Management (short summary) - An API-as-a-Product operating model: governance, lifecycle control, and organization-level scaling practices.
- Web API Design: The Missing Link (short summary) - Resource-oriented API design principles: URI structure, links, and contract evolution without breaking clients.
- Customer-Friendly API: Product approach and design - Developer experience and API predictability as a leverage point for faster product-team integration.
- API Security Patterns - Security controls and policy enforcement as a required layer of mature API governance.
- Architecture at scale: how we make architectural decisions - How API standards connect to architecture decision-making via RFC/ADR workflows and review mechanics.
- API Gateway - Applied API policy execution at the edge: auth, routing, rate limiting, and observability controls.
- Inter-service communication patterns - Where API contract design directly impacts reliability of service-to-service calls and change velocity.