The Playbook

This is the playbook I bring to every team: the decisions I've already made, written down, so they don't have to be re-argued in every new codebase. None of it is novel. Most of it is a published standard (an RFC, a spec, a practice from Stripe, GitHub or Google) applied consistently. The value is in the consistency.

Every doc states a default. Defaults can be overridden, but the override is a decision, and it gets written down (Design Docs & ADRs). This site's own decisions are recorded as ADRs, and CI fails any doc here that drops its references, links to a doc that doesn't exist, or wraps JSON in an envelope.

Principles

These are the rules the rest of the playbook is built from.

1. Standards before inventions. If an RFC, a spec, or a widely adopted practice already solves it, use that. Link for pagination, RFC 3339 for time, Idempotency-Key, RateLimit, Deprecation and Sunset, QUERY. A custom convention has to earn its place.
2. HTTP means what it says. Methods carry intent, status codes carry outcome, headers carry metadata. Bodies carry resources: a list is an array, a single resource is an object, and there are no data envelopes.
3. Make the wrong thing hard. Money is an integer, so it can't drift. State transitions are guarded in the database. Method overrides can only become QUERY. A guardrail beats a guideline.
4. Everything retries, so everything is idempotent. Networks fail after the work is done. Keys, dedupe and at-least-once handling are designed in from the start, not added after the first double charge.
5. Nothing is rewritten. Financial records, events, decisions and incidents are appended, corrected with new entries, and kept explainable.
6. Change is additive. APIs, schemas and events grow without breaking anyone. Breaking changes ship as new versions with a dated, announced sunset.
7. Observable by default. Every request has an ID, every log line is structured, every service has an SLO. If you can't see it, you can't own it.
8. Small, reversible steps. Small PRs, expand-and-contract migrations, flags and progressive rollouts. The cost of a mistake is how hard it is to undo.

The Map

Area	What it covers
Fundamentals	REST & HTTP Verbs, Time & Date Formats, Identifier Conventions
API Design	Principles, Naming, Relationships, Authentication
Requests & Responses	Errors, JSON Fields, Pagination, Filtering & Sorting, HTTP QUERY, Expanding, Caching, Long-Running Operations, Bulk Operations
Operations	Rate Limiting, Versioning, Retries & Timeouts, Observability, SLOs, On-Call, Configuration & Secrets
Payments	Money, Idempotency, Payment States & Ledgers, Webhooks, Sensitive Data
Architecture	Service Boundaries, Events, Multi-Tenancy, Data Retention
Database	Naming, Zero-Downtime Migrations
Engineering Practice	Design Docs & ADRs, Commits & Review, Testing, Feature Flags, Dependencies, Postmortems

Where to Start

• Designing an API? API Design Principles, then Errors, Pagination and Versioning.
• Moving money? Money and Idempotency before writing a line of code.
• Splitting a system? Service Boundaries and Events.
• Running it in production? Observability, SLOs and Postmortems.

References

Specifications

• RFC 9110: HTTP Semantics, the foundation for methods, status codes and headers
• RFC 9205: Building Protocols with HTTP, the IETF's best practice for HTTP APIs

Reference

• MDN: HTTP, the most readable reference for every header, method and status code

In practice

• Stripe: API Reference, the benchmark for payments APIs: idempotency, expansion, versioning
• GitHub Docs: REST API, unwrapped responses, Link pagination and conditional requests
• Google: API Improvement Proposals, design guidance written as numbered, citable decisions
• Microsoft: Azure REST API Guidelines, long-running operations, paging and concurrency at scale
• Zalando: RESTful API Guidelines, a public, opinionated rulebook in the same spirit
• Heroku: HTTP API Design Guide, concise conventions from the Heroku Platform API
• Google: Site Reliability Engineering, SLOs, error budgets and blameless postmortems