API design playbook

An API design playbook for any HTTP and JSON API, public or internal. It covers resources and methods, data formats, errors, lists, change over time, reliability, security, contracts and webhooks.

The rules rest on the HTTP standards, such as RFC 9110 and RFC 9457, and on guides that large API teams publish. Each rule has a check you can run with a single request, a contract test or a linter.

Some endpoints follow an outside protocol, such as MCP, A2A, GraphQL, JSON-RPC, NLWeb or the Reporting API. For those, the protocol's own schema and error format is the contract, and these rules apply to your own REST endpoints.

AI agents call APIs more than they read pages. An API with predictable names, typed errors and a published contract lets an agent use it correctly on the first try.

Chapters

1. Resources and methods

   Name resources as nouns, use each HTTP method for what it means, and answer with the status code that tells the client exactly what happened.

   • Required 4
   • Recommended 1

2. Requests and responses

   Send JSON with one naming style, exact dates, safe money values and string IDs, so every field means the same thing everywhere in the API.

   • Required 6
   • Recommended 2

3. Errors

   Answer every error as RFC 9457 problem details. Give it a stable type, a plain message and the exact fields that failed.

   • Required 4
   • Recommended 1

4. Lists

   Page through long lists with cursors, cap every page, and let clients filter and sort with plain, documented parameters that never change meaning.

   • Required 3
   • Recommended 2

5. Changes over time

   Grow the API by adding, never by breaking. When a break is unavoidable, ship a new version and give clients dates, headers and time to move.

   • Required 3
   • Recommended 2

6. Reliability

   Make retries safe with idempotency keys, protect updates with ETags, set timeouts everywhere and tell clients plainly when to slow down.

   • Required 3
   • Recommended 3

7. API security

   Authenticate every call with scoped tokens, authorise every object, and keep secrets out of addresses. Link to the security playbook for the attacks.

   • Required 5

8. Contracts and docs

   Make an OpenAPI file the single source of truth. Test the API against it, generate docs and clients from it, and publish it for people and agents.

   • Required 2
   • Recommended 3

9. Webhooks and events

   Sign every webhook, retry until it is accepted, and let receivers handle duplicates and out-of-order events without double work.

   • Required 4
   • Recommended 2

All 50 rules on one page