API Design & REST

HTTP Methods at a Glance

Essential Status Codes

Common Headers

Content-Type: application/json

Accept: application/json

Authorization: Bearer <token>

Location: /api/users/42

Cache-Control: max-age=3600

X-Request-ID: a1b2c3d4-e5f6

The 6 REST Constraints

Resources vs Representations

# The resource (conceptual entity)
/api/users/42

# This URI always refers to user 42
# regardless of format or state

# JSON representation
GET /api/users/42
Accept: application/json

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

# XML representation (same resource)
GET /api/users/42
Accept: application/xml

<user>
  <id>42</id>
  <name>Ada Lovelace</name>
</user>

Richardson Maturity Model

A model that grades APIs by how well they use HTTP and REST principles. Each level builds on the one below.

REST vs RPC vs GraphQL

# REST approach
GET /api/users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

# RPC approach (gRPC-style)
service UserService {
  rpc GetUser (GetUserRequest) returns (User);
}

# GraphQL approach
POST /graphql
{
  "query": "{ user(id: 42) { name email orders { id total } } }"
}

Resource Naming Rules

# Good
GET  /users
POST /orders

# Bad
GET  /getUsers
POST /createOrder

# Collection
GET /api/articles

# Single resource
GET /api/articles/507

# Good
/api/user-profiles
/api/order-items

# Bad
/api/userProfiles
/api/order_items

# Good
/api/users

# Bad
/api/users/

# Good
GET /api/reports/annual
Accept: application/pdf

# Bad
GET /api/reports/annual.pdf

# Hierarchy reflects ownership
/api/users/42/orders
/api/users/42/orders/7
/api/shops/12/products

Hierarchical Path Structure

URL paths read like an address, narrowing from general to specific.

# Pattern: /{version}/{resource}/{id}/{sub-resource}/{sub-id}

# API root
/api/v1

# Collection of users
/api/v1/users

# A specific user
/api/v1/users/42

# Orders belonging to user 42
/api/v1/users/42/orders

# A specific order belonging to user 42
/api/v1/users/42/orders/107

# Line items within that order
/api/v1/users/42/orders/107/items

Nested Resources: When to Nest vs Flatten

# Order items belong to an order
GET /orders/107/items
GET /orders/107/items/3

# Comments belong to a post
GET /posts/88/comments

# Seats belong to an event
GET /events/5/seats

# Products exist independently of shops
GET /products?shop_id=12
GET /products/99

# Tags can belong to many resources
GET /tags?resource=posts

# Users exist outside of teams
GET /users?team_id=4

Query Parameters

Query parameters handle filtering, sorting, searching, and pagination — anything that does not identify a resource.

# Filtering
GET /api/products?category=electronics&in_stock=true

# Sorting (prefix with - for descending)
GET /api/products?sort=-price,name

# Searching
GET /api/products?q=wireless+headphones

# Pagination
GET /api/products?page=2&per_page=25

# Field selection (sparse fieldsets)
GET /api/products?fields=id,name,price

# Combining everything
GET /api/products?category=electronics&sort=-price&page=1&per_page=10&fields=id,name,price

URL Versioning Strategies

Method Overview

GET — Retrieve Resources

# Retrieve a collection
GET /api/v1/articles?page=1&per_page=3 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60
X-Total-Count: 142

{
  "data": [
    {
      "id": 301,
      "title": "Understanding REST Constraints",
      "slug": "understanding-rest-constraints",
      "author": { "id": 42, "name": "Ada Lovelace" },
      "publishedAt": "2025-03-15T09:30:00Z",
      "tags": ["api", "architecture"]
    },
    {
      "id": 302,
      "title": "HTTP Caching Deep Dive",
      "slug": "http-caching-deep-dive",
      "author": { "id": 17, "name": "Grace Hopper" },
      "publishedAt": "2025-03-12T14:00:00Z",
      "tags": ["http", "performance"]
    },
    {
      "id": 303,
      "title": "JSON Schema Validation",
      "slug": "json-schema-validation",
      "author": { "id": 42, "name": "Ada Lovelace" },
      "publishedAt": "2025-03-10T11:15:00Z",
      "tags": ["json", "validation"]
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 3,
    "totalPages": 48,
    "totalItems": 142
  }
}

# Retrieve a single resource
GET /api/v1/articles/301 HTTP/1.1
Host: api.example.com
Accept: application/json

# Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "a1b2c3d4"

{
  "id": 301,
  "title": "Understanding REST Constraints",
  "slug": "understanding-rest-constraints",
  "body": "REST (Representational State Transfer) defines six constraints...",
  "author": {
    "id": 42,
    "name": "Ada Lovelace",
    "avatarUrl": "https://cdn.example.com/avatars/42.jpg"
  },
  "publishedAt": "2025-03-15T09:30:00Z",
  "updatedAt": "2025-03-16T08:00:00Z",
  "tags": ["api", "architecture"],
  "readTimeMinutes": 8
}

POST — Create Resources

# Create a new article
POST /api/v1/articles HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "title": "Rate Limiting Strategies",
  "body": "Rate limiting protects your API from abuse and ensures fair usage...",
  "tags": ["api", "security", "infrastructure"],
  "status": "draft"
}

# Response — 201 with Location header pointing to the new resource
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/articles/304

{
  "id": 304,
  "title": "Rate Limiting Strategies",
  "body": "Rate limiting protects your API from abuse and ensures fair usage...",
  "author": { "id": 42, "name": "Ada Lovelace" },
  "tags": ["api", "security", "infrastructure"],
  "status": "draft",
  "createdAt": "2025-03-17T10:45:00Z",
  "updatedAt": "2025-03-17T10:45:00Z"
}

PUT — Replace Resources

# Replace an article entirely — ALL fields required
PUT /api/v1/articles/304 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "title": "Rate Limiting Strategies for Production APIs",
  "body": "Rate limiting protects your API from abuse and ensures fair usage across consumers...",
  "tags": ["api", "security", "infrastructure", "production"],
  "status": "published"
}

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 304,
  "title": "Rate Limiting Strategies for Production APIs",
  "body": "Rate limiting protects your API from abuse and ensures fair usage across consumers...",
  "author": { "id": 42, "name": "Ada Lovelace" },
  "tags": ["api", "security", "infrastructure", "production"],
  "status": "published",
  "createdAt": "2025-03-17T10:45:00Z",
  "updatedAt": "2025-03-17T11:20:00Z"
}

PATCH — Partial Updates

JSON Merge Patch (RFC 7396)

Send only the fields you want to change. Null values remove fields. Simple and intuitive.

# Update only the title and status (other fields unchanged)
PATCH /api/v1/articles/304 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "title": "Rate Limiting Strategies (Updated)",
  "status": "published"
}

# Response — full updated resource
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 304,
  "title": "Rate Limiting Strategies (Updated)",
  "body": "Rate limiting protects your API from abuse...",
  "tags": ["api", "security", "infrastructure", "production"],
  "status": "published",
  "updatedAt": "2025-03-17T12:00:00Z"
}

JSON Patch (RFC 6902)

An ordered sequence of operations. More powerful than merge patch — supports add, remove, replace, move, copy, and test.

# Apply a sequence of operations
PATCH /api/v1/articles/304 HTTP/1.1
Host: api.example.com
Content-Type: application/json-patch+json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

[
  { "op": "replace", "path": "/title", "value": "Advanced Rate Limiting" },
  { "op": "add", "path": "/tags/-", "value": "advanced" },
  { "op": "remove", "path": "/tags/0" },
  { "op": "test", "path": "/status", "value": "published" }
]

# Response
HTTP/1.1 200 OK
Content-Type: application/json

DELETE — Remove Resources

# Delete an article
DELETE /api/v1/articles/304 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Response — first call
HTTP/1.1 204 No Content

# Response — second call (resource already deleted)
# Option A: still 204 (treats "already deleted" as success)
HTTP/1.1 204 No Content

# Option B: 404 (resource no longer exists)
HTTP/1.1 404 Not Found
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Article 304 does not exist"
  }
}

HEAD & OPTIONS

# Check if resource exists + get metadata
HEAD /api/v1/articles/301 HTTP/1.1
Host: api.example.com

# Response — headers only, no body
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1842
ETag: "a1b2c3d4"
Last-Modified: Sat, 16 Mar 2025 08:00:00 GMT

# CORS preflight request (browser-initiated)
OPTIONS /api/v1/articles HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type

# Response — server declares what is allowed
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

2xx — Success

The request was received, understood, and accepted.

# 200 OK — successful retrieval
GET /api/v1/users/42
HTTP/1.1 200 OK
{ "id": 42, "name": "Ada Lovelace", "email": "ada@example.com" }

# 201 Created — new resource, with Location header
POST /api/v1/users
HTTP/1.1 201 Created
Location: /api/v1/users/43
{ "id": 43, "name": "Grace Hopper", "email": "grace@example.com" }

# 202 Accepted — queued for background processing
POST /api/v1/reports/generate
HTTP/1.1 202 Accepted
{ "jobId": "rpt-9a8b7c", "statusUrl": "/api/v1/jobs/rpt-9a8b7c", "estimatedSeconds": 30 }

# 204 No Content — successful delete, nothing to return
DELETE /api/v1/users/44
HTTP/1.1 204 No Content

3xx — Redirection

The client must take additional action to complete the request.

4xx — Client Errors

The request contains bad syntax or cannot be fulfilled. The fault lies with the client.

# 400 — malformed request (invalid JSON syntax)
POST /api/v1/users
Content-Type: application/json
{ "name": "Ada", "email": }          <-- syntax error

HTTP/1.1 400 Bad Request
{ "error": { "code": "INVALID_JSON", "message": "Unexpected token at position 32" } }

# 422 — valid JSON but violates business rules
POST /api/v1/users
Content-Type: application/json
{ "name": "Ada", "email": "ada@example.com" }

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": [
      { "field": "email", "message": "Email address is already registered" }
    ]
  }
}

# 401 — no authentication provided
GET /api/v1/admin/users
(no Authorization header)

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
{ "error": { "code": "AUTH_REQUIRED", "message": "Authentication required" } }

# 403 — authenticated but not an admin
DELETE /api/v1/admin/users/42
Authorization: Bearer eyJ...  (valid token, role=viewer)

HTTP/1.1 403 Forbidden
{ "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "Admin role required" } }

# 409 — conflict with current state
PUT /api/v1/articles/301
If-Match: "a1b2c3d4"    (stale ETag)

HTTP/1.1 409 Conflict
{
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Resource has been modified since your last read",
    "currentETag": "x9y8z7w6"
  }
}

# 429 — rate limit exceeded
GET /api/v1/search?q=test

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710680400
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Try again in 30 seconds." } }

5xx — Server Errors

The server failed to fulfill a valid request. The fault lies with the server.

Request Anatomy

Every HTTP request consists of four parts: method + path, headers, an optional body, and query parameters encoded in the URL.

# [1] Request line: METHOD  PATH  PROTOCOL
POST /api/v1/articles HTTP/1.1

# [2] Headers: metadata about the request
Host: api.example.com
Content-Type: application/json      ← format of the body we are sending
Accept: application/json             ← format we want back
Authorization: Bearer eyJhbGci...    ← authentication credential
X-Request-ID: req-7f3a9b2c          ← correlation ID for tracing
Content-Length: 147                   ← size of the body in bytes

# [3] Blank line separates headers from body

# [4] Body: the payload (JSON, form data, etc.)
{
  "title": "Request Anatomy Explained",
  "body": "Every HTTP request has four parts...",
  "tags": ["http", "tutorial"],
  "status": "draft"
}

Response Anatomy

# [1] Status line: PROTOCOL  STATUS-CODE  REASON
HTTP/1.1 201 Created

# [2] Response headers
Content-Type: application/json       ← format of the response body
Location: /api/v1/articles/305       ← URL of the newly created resource
ETag: "e8f9a0b1"                     ← version tag for conditional requests
Cache-Control: no-cache              ← caching directive
X-Request-ID: req-7f3a9b2c          ← echoed back for correlation
X-RateLimit-Limit: 1000             ← rate limit ceiling
X-RateLimit-Remaining: 997          ← remaining requests in window

# [3] Blank line

# [4] Response body
{
  "id": 305,
  "title": "Request Anatomy Explained",
  "body": "Every HTTP request has four parts...",
  "author": { "id": 42, "name": "Ada Lovelace" },
  "tags": ["http", "tutorial"],
  "status": "draft",
  "createdAt": "2025-03-18T09:00:00Z",
  "updatedAt": "2025-03-18T09:00:00Z"
}

Essential Headers

Content Negotiation

Clients use the Accept header to tell the server which response formats they prefer. Quality values (q) express relative preference from 0 to 1.

# Client prefers JSON, but will accept XML as a fallback
GET /api/v1/articles/301 HTTP/1.1
Accept: application/json, application/xml;q=0.8, text/plain;q=0.5

# Server responds with the best match
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept

{ "id": 301, "title": "Understanding REST Constraints" }

# If the server cannot satisfy any requested format:
HTTP/1.1 406 Not Acceptable
{
  "error": {
    "code": "NOT_ACCEPTABLE",
    "message": "Supported formats: application/json, application/xml",
    "supportedMediaTypes": ["application/json", "application/xml"]
  }
}

JSON Conventions

# Good
{
  "firstName": "Ada",
  "createdAt": "2025-03-15T09:30:00Z",
  "isActive": true
}

# Bad
{
  "first_name": "Ada",
  "created-at": "...",
  "IsActive": true
}

# Good — ISO 8601 with UTC
{
  "createdAt": "2025-03-15T09:30:00Z",
  "expiresAt": "2025-04-15T00:00:00Z"
}

# Bad — ambiguous formats
{
  "created": 1710495000,
  "expires": "03/15/2025"
}

# Good — explicit null
{
  "id": 42,
  "name": "Ada Lovelace",
  "bio": null,
  "avatarUrl": null
}

# Bad — missing fields
{
  "id": 42,
  "name": "Ada Lovelace"
}

Envelope Pattern vs Flat Responses

# Envelope — collection with metadata
{
  "data": [
    { "id": 1, "name": "Ada" },
    { "id": 2, "name": "Grace" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 142
  }
}

# Flat — single resource, no wrapper
{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin"
}

# Metadata goes in headers
ETag: "a1b2c3d4"
Last-Modified: Sat, 15 Mar 2025 09:30:00 GMT

Common Operations — Full HTTP Conversations

List Resources

# Request
GET /api/v1/users?role=admin&sort=-createdAt&page=1&per_page=2 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGci...

# Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 8

{
  "data": [
    { "id": 42, "name": "Ada Lovelace", "email": "ada@example.com", "role": "admin", "createdAt": "2025-01-10T08:00:00Z" },
    { "id": 17, "name": "Grace Hopper", "email": "grace@example.com", "role": "admin", "createdAt": "2025-01-05T12:00:00Z" }
  ],
  "pagination": { "page": 1, "perPage": 2, "totalPages": 4, "totalItems": 8 }
}

Get Single Resource

# Request
GET /api/v1/users/42 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGci...

# Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "u42-v7"

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin",
  "bio": "Mathematician and writer, known for work on the Analytical Engine.",
  "avatarUrl": "https://cdn.example.com/avatars/42.jpg",
  "createdAt": "2025-01-10T08:00:00Z",
  "updatedAt": "2025-03-15T09:30:00Z"
}

Create Resource

# Request
POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGci...

{
  "name": "Alan Turing",
  "email": "alan@example.com",
  "role": "editor"
}

# Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/55

{
  "id": 55,
  "name": "Alan Turing",
  "email": "alan@example.com",
  "role": "editor",
  "bio": null,
  "avatarUrl": null,
  "createdAt": "2025-03-18T10:15:00Z",
  "updatedAt": "2025-03-18T10:15:00Z"
}

Update Resource

# Request — partial update with merge patch
PATCH /api/v1/users/55 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json
Authorization: Bearer eyJhbGci...
If-Match: "u55-v1"

{
  "bio": "Pioneer of theoretical computer science and artificial intelligence.",
  "role": "admin"
}

# Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "u55-v2"

{
  "id": 55,
  "name": "Alan Turing",
  "email": "alan@example.com",
  "role": "admin",
  "bio": "Pioneer of theoretical computer science and artificial intelligence.",
  "avatarUrl": null,
  "createdAt": "2025-03-18T10:15:00Z",
  "updatedAt": "2025-03-18T10:30:00Z"
}

Delete Resource

# Request
DELETE /api/v1/users/55 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

# Response
HTTP/1.1 204 No Content

API Keys

API keys identify the calling application. They are not user credentials — they tell the server which app is making the request, not who the user is.

Header-Based Keys (Recommended)

# Request with API key in header
GET /api/v1/products HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0
Accept: application/json

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 1, "name": "Widget", "price": 9.99 }
  ]
}

Key Prefixes for Safety

# Use prefixes to distinguish key types
sk_live_a1b2c3d4...   # Secret key — server-side only
pk_live_x9y8z7w6...   # Publishable key — safe for client-side
sk_test_m4n5o6p7...   # Test key — sandbox environment

OAuth 2.0

OAuth 2.0 delegates authorization without sharing passwords. The client receives a token that grants limited access on behalf of a user (or itself).

Authorization Code + PKCE (Web & Mobile Apps)

The most secure flow for apps where a user is present. PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks.

# Step 1 — Generate a code verifier and challenge
code_verifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
code_challenge = BASE64URL(SHA256(code_verifier))
               = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

# Step 2 — Redirect user to authorization server
GET https://auth.example.com/authorize
  ?response_type=code
  &client_id=app_abc123
  &redirect_uri=https://app.example.com/callback
  &scope=read:users write:posts
  &state=xYz789randomStateValue
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

# Step 3 — User authenticates, server redirects back with code
https://app.example.com/callback
  ?code=SplxlOBeZQQYbYS6WxSbIA
  &state=xYz789randomStateValue

# Step 4 — Exchange code for tokens (server-side)
POST https://auth.example.com/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://app.example.com/callback
&client_id=app_abc123
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

# Step 5 — Receive tokens
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "scope": "read:users write:posts"
}

Client Credentials (Machine-to-Machine)

For server-to-server communication with no user context. The application authenticates as itself.

# Request a token using client credentials
POST https://auth.example.com/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=client_credentials
&scope=read:analytics

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:analytics"
}

JWT (JSON Web Tokens)

A JWT is a compact, URL-safe token with three Base64URL-encoded parts separated by dots: header.payload.signature.

# JWT structure: header.payload.signature
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiJ1c2VyXzQyIiwibmFtZSI6IkFkYS
BMb3ZlbGFjZSIsInJvbGUiOiJhZG1pbiIsImlhd
CI6MTcxMDUwMDAwMCwiZXhwIjoxNzEwNTAzNjAw
LCJpc3MiOiJhcGkuZXhhbXBsZS5jb20iLCJhdWQ
iOiJhcHBfYWJjMTIzIn0.
SIGNATURE_BYTES_HERE

# Decoded header
{
  "alg": "RS256",
  "typ": "JWT"
}

# Decoded payload
{
  "sub": "user_42",
  "name": "Ada Lovelace",
  "role": "admin",
  "iat": 1710500000,
  "exp": 1710503600,
  "iss": "api.example.com",
  "aud": "app_abc123"
}

JWT Validation Checklist

Bearer Tokens

Bearer tokens are the standard way to pass access tokens in API requests. Any party holding the token can use it — hence the name "bearer."

# Using a bearer token
GET /api/v1/users/me HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "user_42",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin"
}

# If the token is invalid or expired:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
  error_description="The access token has expired"

CORS (Cross-Origin Resource Sharing)

CORS controls which origins (domains) can access your API from a browser. The browser sends a preflight OPTIONS request before the actual request to check permissions.

Preflight Request & Response

# Browser sends preflight OPTIONS request
OPTIONS /api/v1/users HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, Authorization

# Server responds with CORS headers
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true

Common CORS Headers

Rate Limiting

Rate limiting protects your API from abuse and ensures fair usage. The token bucket algorithm is the most common approach: each client has a bucket of tokens that refills at a steady rate. Each request consumes one token.

Rate Limit Headers

# Successful request with rate limit headers
GET /api/v1/products HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1710504000

{
  "data": [ ... ]
}

429 Too Many Requests

# Rate limit exceeded
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710504000

{
  "type": "https://api.example.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 1000 requests per hour. Try again in 30 seconds.",
  "retryAfter": 30
}

Security Checklist

Why Paginate

Returning an entire collection in one response does not scale. A table with 100,000 rows serialized to JSON can exceed 50 MB and take seconds to transmit. Pagination limits response size, reduces database load, and improves perceived performance.

Offset Pagination

The simplest approach. The client specifies how many items to skip (offset) and how many to return (limit). Maps directly to SQL's LIMIT and OFFSET clauses.

# Request — page 6 (items 101-120)
GET /api/v1/products?limit=20&offset=100 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 101, "name": "Ergonomic Keyboard", "price": 89.00 },
    { "id": 102, "name": "USB-C Hub", "price": 45.00 },
    ... 18 more items ...
  ],
  "pagination": {
    "limit": 20,
    "offset": 100,
    "totalItems": 2340,
    "totalPages": 117,
    "currentPage": 6,
    "hasNextPage": true,
    "hasPrevPage": true
  }
}

Cursor Pagination

Instead of counting rows, the server returns an opaque cursor pointing to the last item in the current page. The client passes this cursor to fetch the next page. The cursor is typically a Base64-encoded value of the sort key.

# Request — first page
GET /api/v1/products?limit=20 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 1, "name": "Mechanical Keyboard", "price": 129.00 },
    { "id": 2, "name": "Trackball Mouse", "price": 79.00 },
    ... 18 more items ...
  ],
  "pagination": {
    "limit": 20,
    "hasNextPage": true,
    "hasPrevPage": false,
    "nextCursor": "eyJpZCI6MjAsImNyZWF0ZWRBdCI6IjIwMjUtMDMtMTVUMDk6MzA6MDBaIn0",
    "prevCursor": null
  }
}

# Request — next page using cursor
GET /api/v1/products?limit=20&after=eyJpZCI6MjAsImNyZWF0ZWRBdCI6IjIwMjUtMDMtMTVUMDk6MzA6MDBaIn0 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 21, "name": "Monitor Stand", "price": 59.00 },
    ... 19 more items ...
  ],
  "pagination": {
    "limit": 20,
    "hasNextPage": true,
    "hasPrevPage": true,
    "nextCursor": "eyJpZCI6NDAsImNyZWF0ZWRBdCI6IjIwMjUtMDMtMTRUMTI6MDA6MDBaIn0",
    "prevCursor": "eyJpZCI6MjEsImNyZWF0ZWRBdCI6IjIwMjUtMDMtMTVUMDg6MDA6MDBaIn0"
  }
}

Offset vs Cursor Comparison

Link Header Pagination (RFC 8288)

Instead of pagination metadata in the response body, some APIs (like GitHub) use the standard Link header. This keeps the response body clean and follows the HATEOAS principle.

# Response with Link header pagination
HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.example.com/products?limit=20&after=eyJpZCI6NDB9>; rel="next",
      <https://api.example.com/products?limit=20&before=eyJpZCI6MjF9>; rel="prev",
      <https://api.example.com/products?limit=20>; rel="first"

[
  { "id": 21, "name": "Monitor Stand", "price": 59.00 },
  { "id": 22, "name": "Cable Management Kit", "price": 24.00 },
  ... 18 more items ...
]

Filtering

Filtering lets clients narrow results to exactly what they need, reducing payload size and database load. Use query parameters with clear, consistent naming.

# Simple equality filters
GET /api/v1/products?status=active&category=electronics
GET /api/v1/users?role=admin&department=engineering

# Range filters with suffixes
GET /api/v1/orders?created_after=2024-01-01&created_before=2024-12-31
GET /api/v1/products?price_min=10&price_max=100

# Multiple values (comma-separated)
GET /api/v1/products?status=active,featured&tags=wireless,ergonomic

# Search / full-text filter
GET /api/v1/products?search=mechanical+keyboard

# Combined example — active electronics under $100, created this year
GET /api/v1/products?status=active&category=electronics&price_max=100&created_after=2024-01-01&limit=20 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 42, "name": "Wireless Mouse", "price": 45.00, "status": "active", "category": "electronics" },
    { "id": 78, "name": "USB-C Hub", "price": 39.00, "status": "active", "category": "electronics" }
  ],
  "pagination": { "limit": 20, "offset": 0, "totalItems": 2, "totalPages": 1 },
  "filters": { "status": "active", "category": "electronics", "priceMax": 100, "createdAfter": "2024-01-01" }
}

Sorting

Sorting controls the order of results. Two common patterns exist — choose one and stay consistent across your API.

# Separate sort and order params
GET /api/v1/products
  ?sort=createdAt
  &order=desc

GET /api/v1/products
  ?sort=price
  &order=asc

# Multiple sort fields
GET /api/v1/products
  ?sort=category,price
  &order=asc,desc

# Prefix with - for descending
GET /api/v1/products
  ?sort=-createdAt

GET /api/v1/products
  ?sort=price

# Multiple sort fields
GET /api/v1/products
  ?sort=-category,price

Field Selection (Sparse Fieldsets)

Let clients request only the fields they need. This reduces payload size, especially for resources with many properties or nested objects.

# Request only specific fields
GET /api/v1/users?fields=id,name,email HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

# Response — only requested fields returned
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 1, "name": "Ada Lovelace", "email": "ada@example.com" },
    { "id": 2, "name": "Grace Hopper", "email": "grace@example.com" }
  ]
}

# Without field selection (full response)
GET /api/v1/users HTTP/1.1

# Each user object would include all fields:
# id, name, email, role, bio, avatarUrl, department,
# createdAt, updatedAt, lastLoginAt, preferences, ...

GET /api/v1/users?fields=id,name

query {
  users {
    id
    name
    posts { title }
  }
}

RFC 9457 — Problem Details for HTTP APIs

RFC 9457 (formerly RFC 7807) defines a standard JSON format for error responses. Using this standard means clients only need to learn one error structure, and tooling can parse errors automatically.

# Content-Type for Problem Details responses
Content-Type: application/problem+json

# Basic structure
{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid fields.",
  "instance": "/api/v1/users/42"
}

Problem Details Fields

Error Response Examples

400 — Validation Error

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains 2 invalid fields.",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Must be a valid email address.",
      "rejected": "not-an-email"
    },
    {
      "field": "age",
      "code": "OUT_OF_RANGE",
      "message": "Must be between 13 and 150.",
      "rejected": -5
    }
  ]
}

401 — Authentication Error

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="invalid_token"

{
  "type": "https://api.example.com/errors/token-expired",
  "title": "Authentication Required",
  "status": 401,
  "detail": "The access token expired at 2025-03-15T10:30:00Z. Request a new token using your refresh token.",
  "instance": "/api/v1/users/me",
  "expiredAt": "2025-03-15T10:30:00Z"
}

403 — Authorization Error

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "You need the 'admin:write' permission to delete users.",
  "instance": "/api/v1/users/42",
  "requiredPermissions": ["admin:write"],
  "currentPermissions": ["user:read", "user:write"]
}

404 — Not Found

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No user found with ID 'usr_9999'.",
  "instance": "/api/v1/users/usr_9999",
  "resourceType": "User",
  "resourceId": "usr_9999"
}

429 — Rate Limit Exceeded

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 45
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710504000

{
  "type": "https://api.example.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have sent 1001 requests in the current hour window. Retry after 45 seconds.",
  "instance": "/api/v1/products",
  "retryAfter": 45,
  "limit": 1000,
  "windowSeconds": 3600
}

500 — Internal Server Error

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Our team has been notified. Reference this incident ID when contacting support.",
  "instance": "/api/v1/orders/789",
  "incidentId": "inc_a1b2c3d4e5f6"
}

Error Codes vs Messages

Always include both a machine-readable code and a human-readable message in error responses. They serve different audiences.

# Machine-readable codes
"code": "VALIDATION_ERROR"
"code": "INVALID_FORMAT"
"code": "RESOURCE_NOT_FOUND"
"code": "TOKEN_EXPIRED"
"code": "RATE_LIMIT_EXCEEDED"
"code": "INSUFFICIENT_PERMISSIONS"

# Human-readable messages
"message": "The request body
  contains invalid fields."
"message": "Must be a valid
  email address."
"message": "No user found
  with ID 'usr_9999'."
"message": "The access token
  expired. Please refresh."

Retry-After Header

The Retry-After header tells the client when to try again. It supports two formats. Include it with all 429 responses and optionally with 503 Service Unavailable.

# Format 1 — Delay in seconds (preferred)
Retry-After: 30

# Format 2 — HTTP date (absolute time)
Retry-After: Sun, 16 Mar 2025 10:30:00 GMT

# Full 429 response with Retry-After
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30

{
  "type": "https://api.example.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Try again in 30 seconds."
}

# 503 during maintenance with Retry-After
HTTP/1.1 503 Service Unavailable
Retry-After: Sun, 16 Mar 2025 12:00:00 GMT

{
  "type": "https://api.example.com/errors/maintenance",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Scheduled maintenance in progress. Expected completion at 12:00 UTC."
}

Partial Success — 207 Multi-Status

When a batch operation succeeds for some items and fails for others, return 207 Multi-Status with individual status codes for each item. This avoids the ambiguity of returning 200 (hiding failures) or 400 (hiding successes).

# Batch request — create multiple users
POST /api/v1/users/batch HTTP/1.1
Content-Type: application/json

{
  "items": [
    { "name": "Ada Lovelace", "email": "ada@example.com" },
    { "name": "Grace Hopper", "email": "invalid-email" },
    { "name": "Alan Turing", "email": "alan@example.com" }
  ]
}

# Response — 207 Multi-Status
HTTP/1.1 207 Multi-Status
Content-Type: application/json

{
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  },
  "results": [
    {
      "index": 0,
      "status": 201,
      "data": { "id": 101, "name": "Ada Lovelace", "email": "ada@example.com" }
    },
    {
      "index": 1,
      "status": 400,
      "error": {
        "type": "https://api.example.com/errors/validation-error",
        "title": "Validation Error",
        "detail": "Invalid email format.",
        "errors": [{ "field": "email", "code": "INVALID_FORMAT", "message": "Must be a valid email address." }]
      }
    },
    {
      "index": 2,
      "status": 201,
      "data": { "id": 102, "name": "Alan Turing", "email": "alan@example.com" }
    }
  ]
}

Error Handling Best Practices

Why Version Your API

Every public API will eventually need to change. New features require new fields. Business pivots require structural changes. Without versioning, any change risks breaking existing clients. A versioning strategy gives you a clear upgrade path: old clients keep working while new clients adopt the latest contract.

You need a new version when you must make a breaking change — removing a field, changing a type, or restructuring a response. If you can add features without breaking existing behavior, you do not need a new version.

Versioning Strategies

URL Path Versioning in Practice

# Version in the base path, before the resource
GET  /api/v1/users          # Version 1 — original
GET  /api/v2/users          # Version 2 — new response format

# Both versions run simultaneously
GET  /api/v1/users/42       # Returns flat user object
GET  /api/v2/users/42       # Returns user with nested profile

# Routing pattern (Express.js example)
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

# Reverse proxy routing (nginx)
location /api/v1/ {
    proxy_pass http://api-v1-service/;
}
location /api/v2/ {
    proxy_pass http://api-v2-service/;
}

Version only the major version in the URL. Minor and patch changes should be backward-compatible and deployed in place. If you find yourself at /v14/, your breaking-change threshold is too low.

Breaking vs Non-Breaking Changes

Deprecation & Sunset

When retiring an API version, use the Deprecation and Sunset headers (RFC 8594) to give clients advance notice. A deprecation means "this still works but will be removed." A sunset means "this is the date it stops working."

# Response headers for a deprecated endpoint
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: Sun, 01 Jan 2025 00:00:00 GMT
Sunset: Sun, 01 Jul 2025 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

# Deprecation notice in response body (optional but helpful)
{
  "data": [ ... ],
  "_deprecation": {
    "message": "API v1 is deprecated. Migrate to v2 by July 1, 2025.",
    "migration_guide": "https://docs.example.com/migrate-v1-to-v2",
    "sunset_date": "2025-07-01"
  }
}

Migration Notices

Every deprecation should come with a migration guide. Include these in your deprecation notices:

OpenAPI / Swagger

The OpenAPI Specification (formerly Swagger) is the industry standard for describing REST APIs. It defines your endpoints, request/response schemas, authentication, and error formats in a machine-readable YAML or JSON file. Tools like Swagger UI, Redoc, and Postman can consume this spec to generate interactive documentation automatically.

# openapi.yaml — OpenAPI 3.1 example
openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
  description: Manage user accounts and profiles.
  contact:
    email: api-support@example.com

servers:
  - url: https://api.example.com/v1
    description: Production

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: A paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{id}:
    get:
      summary: Get a user by ID
      operationId: getUser
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    User:
      type: object
      required: [id, email, name]
      properties:
        id:
          type: integer
          example: 42
        email:
          type: string
          format: email
          example: ada@example.com
        name:
          type: string
          example: Ada Lovelace
        created_at:
          type: string
          format: date-time

    Pagination:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer

    ProblemDetail:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string

  responses:
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'

Documentation Best Practices

API Testing Types

Testing with curl

# GET request with authentication
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Accept: application/json" \
  | jq .

# POST request with JSON body
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "role": "admin"
  }'

# Verbose mode — see request/response headers
curl -v -X GET https://api.example.com/v1/users/42

# Test error handling — expect a 404
curl -s -o /dev/null -w "%{http_code}" \
  https://api.example.com/v1/users/99999
# Output: 404

# Time the request (connection + transfer)
curl -s -o /dev/null \
  -w "connect: %{time_connect}s\ntotal: %{time_total}s\n" \
  https://api.example.com/v1/users

Contract Testing

Contract tests verify that an API producer and its consumers agree on the shape of requests and responses. They catch breaking changes before deployment — without spinning up the full system.

# Schemathesis — fuzz your API against its OpenAPI spec
pip install schemathesis
st run --checks all https://api.example.com/openapi.json

# Pact — consumer-driven contract test (JavaScript)
const { PactV4 } = require('@pact-foundation/pact');

const pact = new PactV4({ consumer: 'WebApp', provider: 'UsersAPI' });

pact.addInteraction({
  states: [{ description: 'user 42 exists' }],
  uponReceiving: 'a request for user 42',
  withRequest: {
    method: 'GET',
    path: '/api/v1/users/42',
    headers: { Accept: 'application/json' },
  },
  willRespondWith: {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
    body: {
      id: 42,
      name: 'Ada Lovelace',
      email: 'ada@example.com',
    },
  },
});

API Design Checklist

HATEOAS

Hypermedia as the Engine of Application State (HATEOAS) means your API responses include links that tell the client what it can do next. Instead of hard-coding URLs, clients follow links — like clicking through a website.

# GET /api/v1/orders/1234
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1234,
  "status": "pending",
  "total": 89.99,
  "currency": "USD",
  "created_at": "2025-03-15T10:30:00Z",
  "_links": {
    "self":    { "href": "/api/v1/orders/1234" },
    "approve": { "href": "/api/v1/orders/1234/approve", "method": "POST" },
    "cancel":  { "href": "/api/v1/orders/1234/cancel",  "method": "POST" },
    "items":   { "href": "/api/v1/orders/1234/items" },
    "customer": { "href": "/api/v1/customers/567" }
  }
}

# After the order is approved, the links change:
{
  "id": 1234,
  "status": "approved",
  "total": 89.99,
  "_links": {
    "self":   { "href": "/api/v1/orders/1234" },
    "ship":   { "href": "/api/v1/orders/1234/ship", "method": "POST" },
    "refund": { "href": "/api/v1/orders/1234/refund", "method": "POST" },
    "items":  { "href": "/api/v1/orders/1234/items" }
  }
}

Idempotency Keys

Network failures happen. Clients retry. Without idempotency keys, a retried POST /payments might charge the customer twice. An idempotency key lets the server recognize a duplicate request and return the original response instead of processing it again.

# Client generates a UUID and sends it with the request
POST /api/v1/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 8a3b9c7e-4d2f-4a1b-9e6c-3f8d7a2b1c0e

{
  "amount": 2500,
  "currency": "USD",
  "customer_id": "cus_abc123",
  "description": "Monthly subscription"
}

# First request — server processes and stores the key + response
HTTP/1.1 201 Created
Idempotency-Key: 8a3b9c7e-4d2f-4a1b-9e6c-3f8d7a2b1c0e

{
  "id": "pay_xyz789",
  "amount": 2500,
  "status": "succeeded"
}

# Retry with same key — server returns cached response (no double charge)
HTTP/1.1 201 Created
Idempotency-Key: 8a3b9c7e-4d2f-4a1b-9e6c-3f8d7a2b1c0e

{
  "id": "pay_xyz789",
  "amount": 2500,
  "status": "succeeded"
}

Store idempotency keys server-side with the response for 24 to 48 hours. Use UUIDs (v4) for key generation. This pattern is used by Stripe, PayPal, and most payment APIs.

Caching

Proper caching reduces server load, lowers latency, and saves bandwidth. HTTP has built-in caching mechanisms — use them instead of inventing your own.

# Server responds with ETag (a fingerprint of the response)
GET /api/v1/users/42 HTTP/1.1

HTTP/1.1 200 OK
ETag: "a1b2c3d4e5f6"
Cache-Control: private, max-age=60
Content-Type: application/json

{ "id": 42, "name": "Ada Lovelace", "email": "ada@example.com" }

# Client sends conditional request with If-None-Match
GET /api/v1/users/42 HTTP/1.1
If-None-Match: "a1b2c3d4e5f6"

# Data hasn't changed — server returns 304 with no body
HTTP/1.1 304 Not Modified
ETag: "a1b2c3d4e5f6"
Cache-Control: private, max-age=60

# Common Cache-Control directives
Cache-Control: public, max-age=3600     # CDN + browser cache for 1 hour
Cache-Control: private, max-age=60      # Browser only, 1 minute
Cache-Control: no-cache                 # Always revalidate with server
Cache-Control: no-store                 # Never cache (sensitive data)

Webhooks

Polling wastes resources. Webhooks flip the model: instead of the client asking "did anything change?" every few seconds, the server pushes events to the client when something happens.

# 1. Client registers a webhook endpoint
POST /api/v1/webhooks HTTP/1.1
Content-Type: application/json

{
  "url": "https://myapp.example.com/hooks/orders",
  "events": ["order.created", "order.shipped", "order.refunded"],
  "secret": "whsec_abc123..."
}

# 2. When an event occurs, the server POSTs to the registered URL
POST https://myapp.example.com/hooks/orders HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: evt_789xyz
X-Webhook-Timestamp: 1710500000

{
  "event": "order.shipped",
  "timestamp": "2025-03-15T14:00:00Z",
  "data": {
    "order_id": 1234,
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS"
  }
}

# 3. Client verifies the signature and responds with 200
HTTP/1.1 200 OK

Anti-Patterns