REST API Designer

Design HTTP interfaces that stay predictable for a decade.

When to use

New endpoints, API reviews, OpenAPI authoring, versioning and deprecation plans, error-model design.

Do not use for: GraphQL or gRPC schema design, internal function signatures, or event/message schemas (different constraints entirely).

Workflow

1. Model resources, not actions

Start from the nouns the client cares about, not the internal tables or the service methods.

• Plural, lowercase, hyphenated collections: /purchase-orders, not /getPurchaseOrder or /purchaseOrders.
• Nest at most one level to express ownership: /orders/{orderId}/items. Beyond that, use a top-level collection with a filter: /items?orderId=123.
• Never put a verb in a path when a method expresses it.
• For genuine actions that are not CRUD, use a sub-resource with POST: POST /orders/{id}/cancellation or POST /orders/{id}:cancel. Document the choice once and apply it everywhere.
• Identifiers in paths are opaque strings. Prefer ULID/UUID over sequential integers in public APIs (no enumeration, no business leakage).

2. Choose the method by its contract

* Make PATCH idempotent when possible; avoid relative operations like "increment": 1.

3. Status codes — a small, disciplined set

Rules: never return 200 with {"error": ...} inside; never invent codes; choose 400 vs 422 once and stay consistent.

4. One error model everywhere

Use RFC 9457 Problem Details:

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "2 fields are invalid.",
  "instance": "/orders/01J8X2",
  "traceId": "0af7651916cd43dd8448eb211c80319c",
  "errors": [
    { "field": "email",    "code": "format",  "message": "Must be a valid email." },
    { "field": "quantity", "code": "min",     "message": "Must be at least 1." }
  ]
}

Every error carries a stable machine-readable code, a human message, and a correlation id. Never expose internals (SQL, hostnames, stack traces).

5. Collections: pagination, filtering, sorting

Cursor pagination is the default — stable under concurrent writes and cheap at depth:

GET /orders?limit=50&cursor=eyJpZCI6IjAxSjhYIn0
→ { "data": [...], "pagination": { "nextCursor": "...", "hasMore": true } }

Offset pagination is acceptable only for small, static datasets that need page numbers. Always cap limit (e.g. max 100) and document the default.

Filtering: ?status=paid&createdAfter=2026-01-01. Reserve ?q= for free-text search. For ranges use explicit ...After / ...Before parameters rather than operator-in-value syntax (?amount=gt:100) — the latter is hard to type-check.

Sorting: ?sort=-createdAt,name (leading - for descending). Whitelist the sortable fields.

Sparse fields: ?fields=id,name,status. Expansion: ?expand=customer, bounded to one level.

6. Consistency contracts

• Naming: pick camelCase or snake_case for JSON bodies and never mix. Query parameters follow the same convention.
• Dates: RFC 3339 UTC strings (2026-07-28T14:03:00Z). Never epoch ints, never local time.
• Money: minor-unit integer + ISO 4217 currency ({"amount": 1999, "currency": "EUR"}). Never floats.
• Enums: lowercase snake strings. Clients must tolerate unknown values.
• Booleans: name them positively (enabled, not isNotDisabled).
• Nulls: null means "explicitly empty"; omit a field to mean "unknown". Never use "" or -1 as a sentinel.
• Envelope: wrap collections in {"data": [...], "pagination": {...}}; return single resources unwrapped. Be consistent across the whole API.

7. Reliability primitives

8. Versioning and deprecation

Version in the URL path (/v1/...) for public APIs — visible, cache-friendly, trivially routable. Media-type versioning is more elegant and less used; pick one.

Non-breaking (ship freely): adding an endpoint, an optional request field, a response field, or a new enum value if clients were told to tolerate them.

Breaking (needs a new version): removing or renaming a field, changing a type, making an optional field required, tightening validation, changing a status code, changing pagination semantics, changing default behaviour.

Deprecation: announce → send Deprecation and Sunset headers → monitor usage per client → contact remaining callers → return 410 after the sunset date. Minimum 6 months for a public API.

9. Security baseline

TLS only. OAuth 2.1 / OIDC bearer tokens for user context, mTLS or signed keys for service-to-service. Validate every input against a schema and reject unknown fields on write. Authorise per resource instance, never only per route. Return 404 rather than 403 when existence itself is sensitive. Rate-limit per principal. Never accept id, role, ownerId or createdAt from the client on create.

10. Emit the OpenAPI 3.1 spec

Produce a spec with: reusable components/schemas, shared responses for every error, securitySchemes, examples on each operation, operationId in camelCase, and tags grouping. Validate it before delivering.

Tools

python3 scripts/openapi_lint.py openapi.json --format md
python3 scripts/openapi_lint.py openapi.yaml --min-severity warning   # CI gate

It checks verbs in paths, nesting depth, method semantics, status-code coverage, Location headers, pagination and its cap, idempotency keys, security schemes, money-as-float, date formats, naming consistency and missing examples. Exit code 1 on any error-level finding.

Worked example

Requirement: "Let customers cancel an order and get a refund."

Design

POST /v1/orders/{orderId}/cancellation
Idempotency-Key: 8f1c...            (required)
If-Match: "W/\"v7\""                (optional, optimistic concurrency)

{ "reason": "customer_request", "note": "Ordered the wrong size" }

201 Created
Location: /v1/orders/01J8X2/cancellation
{
  "id": "01J8XC",
  "orderId": "01J8X2",
  "status": "pending_refund",
  "reason": "customer_request",
  "refund": { "amount": 4999, "currency": "EUR", "status": "processing" },
  "createdAt": "2026-07-28T14:03:00Z"
}

Errors: 404 unknown order · 409 already cancelled or already shipped · 412 stale If-Match · 422 invalid reason code · 403 not the order owner.

Why not POST /v1/cancelOrder — a verb path cannot be cached, cannot be referenced, and cannot report its own state. Cancellation is a real entity with an id, a status and a refund; modelling it as a sub-resource makes it queryable and retry-safe.

Quality checklist

• openapi_lint.py passes with no error-level findings
• No verbs in resource paths (except a documented :action convention)
• Nesting depth ≤ 1
• Every method matches its safety/idempotency contract
• Every endpoint documents 401, 403, 404, 422, 429 and 500
• One error format across the whole API
• Collections paginated with a capped limit
• Dates RFC 3339 UTC; money in minor units with a currency
• Naming convention uniform across paths, params and bodies
• Unsafe non-idempotent operations accept Idempotency-Key
• Breaking-change audit done; version bumped if needed
• OpenAPI 3.1 spec validates and includes examples