API Design Cheatsheet

REST Basics

• Plural nouns, lowercase, hyphenated: /users/42/orders.
• No verbs in path — the HTTP method is the verb.
• Richardson: L2 (verbs + codes) is the practical target; L3 = HATEOAS.
• Never return 200 with an error body.

Methods

Status Codes

4xx = client, don't retry. 5xx = server, retry w/ backoff.

Versioning & Paging

Bump only on breaking changes. Prefer cursor over offset pagination for scale.

Reliability Headers

• Idempotency-Key — safe POST retries.
• Retry-After + RateLimit-* on 429.
• ETag + If-None-Match → 304.
• If-Match → optimistic concurrency.
• Cache-Control freshness.

Errors — RFC 9457

Content-Type: application/problem+json
{
  "type": "/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "email invalid",
  "instance": "/users"
}

Auth

• API key — server-to-server identity.
• OAuth 2.0 — delegated third-party, scopes.
• JWT bearer — stateless, short-lived + refresh.
• Always TLS; never secrets in query string.

REST vs GraphQL vs gRPC

Webhooks: signed (HMAC), event ID for dedup, retry w/ backoff.