API Design

API Design

Apply these conventions when designing, reviewing, or implementing RESTful APIs. Consistency matters more than cleverness — follow the patterns below.

URL Structure

Use nouns for resources, not verbs. Resources are things, not actions.

Query Parameters

Use query parameters for filtering, sorting, searching, and pagination. Never encode these in the URL path.

GET /users?status=active&sort=-created_at&limit=20&cursor=abc123
GET /orders?user_id=42&min_total=100&fields=id,status,total

HTTP Methods

*PATCH is not inherently idempotent but can be implemented as such. Treat it as non-idempotent by default.

Key rules:

• GET must never mutate state. Ever.
• PUT replaces the entire resource — omitted fields are removed or reset to defaults.
• PATCH updates only the fields included in the body.
• POST to a collection creates a new resource. Return the created resource with its id.
• DELETE should succeed silently if the resource is already gone (idempotent).

Status Codes

Use the most specific appropriate code. Don't return 200 for everything.

2xx — Success

4xx — Client Error

5xx — Server Error

Error Format

Return errors in a consistent shape. Every error response uses this structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "details": [
      { "field": "email", "message": "Must be a valid email address." },
      { "field": "age", "message": "Must be at least 18." }
    ]
  }
}

Rules:

• Always return the same top-level { error: { ... } } shape for all error responses.
• Use code for programmatic handling (clients switch on it), message for display.
• Never expose stack traces, internal paths, or database errors in production.
• Include a request_id in error responses (or top-level meta) for debugging.

Pagination

Cursor-Based (Preferred)

Use cursor-based pagination by default. It handles inserts/deletes gracefully and scales to large datasets.

Request:

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ

Response:

{
  "data": [ { "id": 101, "name": "Ada" }, { "id": 102, "name": "Bob" } ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAyfQ",
    "has_more": true
  }
}

Offset-Based (When Needed)

Use offset pagination only when users need to jump to arbitrary pages (admin tables, search results).

Request:

GET /users?offset=40&limit=20

Response:

{
  "data": [ { "id": 41, "name": "Ada" } ],
  "pagination": {
    "offset": 40,
    "limit": 20,
    "total": 523
  }
}

Warning: Offset pagination degrades on large datasets (DB must skip offset rows). Never use for infinite scroll.

Authentication

Bearer Tokens (Preferred for User Auth)

Pass tokens in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

• Use short-lived access tokens (15 min–1 hr) with refresh tokens.
• Validate tokens on every request. Don't cache validation results.
• Return 401 for missing/expired tokens, 403 for insufficient permissions.

API Keys (For Server-to-Server)

Pass API keys in a custom header or as a query parameter (header preferred):

X-API-Key: sk_live_abc123def456

When to Use Each

Versioning

URL Versioning (Preferred)

Prefix major versions in the URL path:

GET /v1/users
GET /v2/users

• Version only when you introduce breaking changes.
• Run old versions in parallel during migration. Set a sunset date and communicate it.
• Non-breaking additions (new optional fields, new endpoints) do not require a version bump.

Header Versioning (Alternative)

Accept: application/vnd.myapi.v2+json

Use header versioning when URL versioning creates routing complexity or you need fine-grained version control. URL versioning is simpler for most cases.

What Counts as a Breaking Change

Rate Limiting

Include rate-limit headers in every response so clients can self-regulate:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1702483200

When the limit is exceeded, return:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 30 seconds.",
    "details": {
      "retry_after": 30
    }
  }
}

Return 429 Too Many Requests with a Retry-After header (in seconds).

Anti-Patterns

Avoid these. When you see them in a codebase, flag or refactor.