api-design

Principles for HTTP/REST APIs that are predictable, debuggable, and pleasant to consume. Opinionated where the field has converged; flexible where reasonable people disagree.

¶When to use

• "Design an endpoint for X"
• "How should this API look?"
• "Review this API"
• "Add an endpoint to …"

¶Procedure

1. Anchor to existing patterns. Read 2–3 existing endpoints in the same codebase. New endpoints should look like neighbors.
2. Model the resource, not the action. Most actions become CRUD on a resource. If they don't (e.g. "publish"), see "Actions on resources" below.
3. Sketch the contract before writing code: path, method, request body, response body, status codes, errors.
4. Check it against the consistency checklist below.
5. Document it — even one paragraph in the PR is better than nothing.

¶Resource naming

• Use plural nouns for collections: /users, /orders, /articles
• Use IDs, not slugs, for identity: /users/42 (slugs are for SEO, not for APIs)
• Nest to express ownership, max 2 levels deep:
  • ✅ /users/42/orders
  • ❌ /users/42/orders/7/items/3/shipments
• Use kebab-case in paths: /account-settings, not /accountSettings or /account_settings
• Lowercase everything in paths
• No verbs in paths — the HTTP method is the verb

¶Methods

* PATCH can be idempotent if you design it that way; don't rely on it.

¶Status codes

Pick from this short list. Resist the urge to be clever.

Don't invent custom codes. Don't return 200 with {"error": "..."}.

¶Errors

Use a single, documented error shape across the entire API:

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation.",
    "details": [
      { "field": "email", "code": "invalid_format" },
      { "field": "age", "code": "must_be_positive" }
    ],
    "request_id": "req_01HX…"
  }
}

• Stable, machine-readable code (snake_case, never localized)
• Human-readable message (English; localize on the client)
• details for per-field validation
• request_id for support / log correlation

Consider RFC 9457 Problem Details if the consumer already uses it.

¶Pagination

Pick one and stick with it across the API.

• Cursor-based (preferred for large/changing data):
  • Request: ?limit=50&cursor=eyJpZCI6...
  • Response: { "data": [...], "next_cursor": "...", "has_more": true }
• Page-based (fine for small/static data):
  • Request: ?page=2&per_page=50
  • Response: { "data": [...], "page": 2, "per_page": 50, "total": 1234 }

Always cap limit / per_page server-side. Document the max.

¶Filtering, sorting, sparse fields

• Filter: ?status=active&created_after=2025-01-01
• Sort: ?sort=-created_at,name (leading - = descending)
• Sparse fields: ?fields=id,email,created_at

¶Versioning

Pick one strategy and commit:

• URL: /v1/users — most visible, easiest to route
• Header: Accept: application/vnd.example.v1+json — cleaner URLs, harder to debug
• Avoid query-string versioning

Only bump the major version for breaking changes. Additive changes (new fields, new endpoints) don't require a new version.

¶Actions on resources

When CRUD doesn't fit (publish, archive, retry, refund), prefer:

• State transitions via PATCH: PATCH /articles/42 {"status": "published"} — best if you have multiple states
• Sub-resources for explicit actions: POST /articles/42/publish — pragmatic when the action has side effects or its own payload

Don't go full RPC: POST /publishArticle?id=42. You're using HTTP; use it.

¶Consistency checklist

• Resource name is a plural noun
• Path uses kebab-case and lowercase
• HTTP method matches semantics (idempotency!)
• Status codes from the short list
• Error response matches the API-wide error shape
• POST that creates returns 201 + Location header
• List endpoints paginate and cap limit
• Timestamps are ISO 8601 with timezone (2026-05-22T14:30:00Z)
• IDs are opaque strings (not auto-increment ints leaked) when possible
• No sensitive data in URLs (use headers / body)
• Versioning strategy followed
• Authentication / authorization checks documented per endpoint

¶Anti-patterns

• ❌ GET /getUser?id=42 — verb in path, query param for identity
• ❌ POST /users/delete/42 — DELETE exists for a reason
• ❌ Returning 200 with {"success": false}
• ❌ Inconsistent casing: userId in one response, user_id in another
• ❌ Auto-increment IDs in URLs leaking row counts to the public
• ❌ Pagination with no upper bound on limit
• ❌ Mixing snake_case and camelCase in the same payload
• ❌ "Soft 200" — returning HTTP success but logical failure