API design checklist

Every rule in the api design playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it.

Resources and methods

• Required Name resources as plural nouns
• Required Use each method for what it means
• Required Answer with the right status code
• Required Keep addresses stable
• Recommended Return 405 with the allowed methods

Requests and responses

• Required Use JSON with one naming style
• Required Send dates as RFC 3339 with a time zone
• Required Send money as an integer with its currency
• Required Send IDs as strings
• Required Give every response one shape
• Required Accept only fields you know
• Required Set caching headers on every response
• Recommended Use enums for fixed values
• Recommended Say which format PATCH accepts

Errors

• Required Send errors as problem details
• Required Keep error types stable
• Required Name every field that failed
• Required Hide internals in errors
• Recommended Say when to retry

Lists

• Required Page lists with cursors
• Required Cap the page size
• Required Return empty lists as empty
• Recommended Filter with plain parameters
• Recommended Sort in a stable order

Changes over time

• Required Make only additive changes
• Required Version only for breaking changes
• Required Announce deprecation and sunset in headers
• Recommended Tell clients to ignore what they don't know
• Recommended Keep a changelog

Reliability

• Required Accept idempotency keys on POST
• Required Retry with backoff and jitter
• Required Set timeouts on every call
• Recommended Stop lost updates with ETags
• Recommended Tell clients their rate limit
• Recommended Run long jobs asynchronously

API security

• Required Authenticate with tokens in headers
• Required Grant narrow scopes
• Required Authorise every object
• Required Keep secrets out of addresses
• Required Store API keys as hashes
• Required Refuse plain HTTP on the API
• Required List every API you run

Contracts and docs

• Required Write the contract first
• Required Test the API against its contract
• Recommended Give every endpoint an example
• Recommended Generate docs and clients from the contract
• Recommended Make the API easy for agents to find

Webhooks and events

• Required Sign every webhook
• Required Retry until the receiver accepts
• Required Make receivers idempotent
• Required Check webhook addresses before sending
• Recommended Don't rely on event order
• Recommended Version event payloads

Files and uploads

• Required Confirm every upload on the server
• Required Scan files for malware before anyone opens them
• Required Rebuild every uploaded image
• Required Serve private files through short-lived links
• Required Delete files when their owner is deleted
• Recommended Upload straight to storage with a signed address
• Recommended Make large uploads resumable
• Recommended Lay out storage by owner and let rules clean it
• Optional Store the same file once per owner