rest_design v1.0.0

name: "rest_design" description: "Design REST APIs: resource naming conventions, which HTTP status code to use when, offset vs cursor pagination, URL versioning, and error-envelope conventions. Triggers on 'design an API', 'REST endpoint', 'which status code', 'pagination', 'offset vs cursor', 'API versioning', 'API design review'." metadata: { "includeInPrompt": true }

differs from graphql-basics because this is REST-specific: resource naming, HTTP status codes, offset/cursor pagination; differs from api-auth-patterns because auth schemes are out of scope here.

REST Design

Purpose

Give agents a concrete, opinionated recipe for designing REST APIs: how to name resources, which status code to return in each situation, how to paginate, how to version, and what error responses look like. Use it when drafting a new API or reviewing an existing one.

Workflow

1. Name resources, not actions

• Plural nouns, always. /orders, not /order or /getOrders.
• Hierarchy for ownership. /customers/{id}/orders — an order belongs to a customer. Cap nesting at 2 levels; deeper than that, flatten (/orders?customer_id=...).
• No verbs in paths. Creating is POST /orders; cancelling is a sub-resource POST /orders/{id}/cancellations, or, for verbs that resist nouning, a colon-suffixed custom method POST /orders/{id}:cancel (Google API convention). Pick one style per API and never mix.
• Filtering, sorting, and searching live in query params, never in the path: GET /orders?status=paid&sort=-created_at&min_total=1000.
• Kebab-case in paths, one convention everywhere. /line-items, not a mix of /lineItems and /line_items.
• Idempotency-safe design:
• GET/HEAD/OPTIONS must be safe (no side effects) and GET must be cacheable where sensible.
• Creation is POST + Idempotency-Key request header (client-generated UUID); the server replays the original response for a repeated key instead of creating a duplicate.
• Full replace is PUT with a client-chosen id (PUT /webhooks/wh_abc); partial update is PATCH with a JSON merge-patch body.
• DELETE is naturally idempotent — deleting an already-deleted resource returns 204 (or 404; pick one and document it).

2. Return the right status code

| Code | Meaning | Use when | |------|---------|----------| | 200 | OK | Successful GET, or POST/PATCH that returns the updated representation. | | 201 | Created | A POST created a resource. Always include a Location header pointing at the new resource. | | 204 | No Content | Successful DELETE, or a PUT/POST with nothing to return. No body. | | 400 | Bad Request | Malformed request: bad JSON, bad query-param types, missing required field. | | 401 | Unauthorized | Missing or invalid credentials. The client can retry with auth. | | 403 | Forbidden | Authenticated, but not allowed (wrong role, not the owner). Do not leak whether the resource exists — prefer 404 for existence-hiding. | | 404 | Not Found | No such resource (or you are hiding existence from a 403). | | 409 | Conflict | State conflict: duplicate unique key, version/etag mismatch, transition not allowed (e.g. refunding an already-refunded order). | | 422 | Unprocessable Entity | Well-formed request that fails semantic validation ("quantity must be >= 1"). Keeps validation distinct from malformed syntax (400). | | 429 | Too Many Requests | Rate limited. Always include a Retry-After header (seconds). | | 500 | Internal Server Error | Unexpected server failure. Generic message only — never leak stack traces. | | 503 | Service Unavailable | Temporarily down or overloaded. Include Retry-After when you know the recovery window. |

Hard rule: never return 200 with an error body. Errors ride on 4xx/5xx. Clients, caches, and load balancers all key off the status line; a 200-that-failed breaks every one of them.

3. Paginate deliberately: offset vs cursor

Offset/limit — GET /orders?limit=20&offset=40

• Request: limit (page size, cap it server-side, e.g. max 100), offset (rows to skip).
• Response shape (fictional api.example.com):

json
{
  "data": [
    {"id": "ord_101", "total_cents": 4999, "created_at": "2026-09-20T14:00:00Z"},
    {"id": "ord_102", "total_cents": 1299, "created_at": "2026-09-20T14:01:12Z"}
  ],
  "meta": {"limit": 2, "offset": 40, "total": 1287},
  "links": {
    "self": "https://api.example.com/v1/orders?limit=2&offset=40",
    "next": "https://api.example.com/v1/orders?limit=2&offset=42",
    "prev": "https://api.example.com/v1/orders?limit=2&offset=38"
  }
}

• Use offset when the client needs random access ("go to page 7") and the dataset is small and stable: admin tables, settings lists. The total count is expensive on big tables — omit it there.

Cursor/keyset — GET /orders?limit=20&cursor=eyJpZCI6...

• Request: limit, plus an opaque cursor returned by the previous page. First page omits cursor.
• Response shape (fictional api.example.com):

json
{
  "data": [
    {"id": "ord_842", "total_cents": 2199, "created_at": "2026-09-21T09:12:03Z"},
    {"id": "ord_841", "total_cents": 899, "created_at": "2026-09-21T09:10:44Z"}
  ],
  "page": {"next_cursor": "eyJpZCI6Im9yZF84NDEiLCJ0cyI6IjIwMjYtMDktMjFUMDk6MTA6NDRaIn0", "has_more": true}
}

• Cursor encoding: base64url of a JSON object holding the sort key of the last row — e.g. {"id":"ord_841","ts":"2026-09-21T09:10:44Z"}. The server decodes it and queries WHERE (created_at, id) < (ts, id) ORDER BY created_at DESC, id DESC LIMIT 20. Clients treat the cursor as opaque; never let clients construct one.
• The sort key must be stable and unique: always add a tie-breaker (id) after the visible sort column, or equal timestamps produce duplicates/skips.
• Use cursor for feeds, infinite scroll, and any list that changes while paged — the common case. Default to cursor unless you have a reason not to.

Why offset breaks under concurrent inserts (worked example): Rows newest-first, page size 5. At t0: [r10, r9, r8, r7, r6, r5, r4, r3, r2, r1].

1. Client fetches ?limit=5&offset=0 → [r10, r9, r8, r7, r6].
2. Two new rows insert at the head: list is now [r12, r11, r10, r9, r8, r7, r6, ...].
3. Client fetches ?limit=5&offset=5 → server skips the first 5 rows (r12, r11, r10, r9, r8) → returns [r7, r6, r5, r4, r3].
4. r7 and r6 were already on page 1 — duplicates; deletes between pages cause the mirror problem, skips. With cursor pagination, step 3 would be "rows strictly older than r6's sort key", which inserts at the head cannot disturb.

Live sanity check of your query-string shape (httpbin echoes the request back; verified 2026-09-22, ~1.3s through the default env proxy — do not use --noproxy '*'):

bash
curl -s 'https://httpbin.org/get?limit=2&offset=4&sort=-created_at' | python3 -m json.tool

httpbin is not a paginated API — it only proves your params are well-formed before you point at a real backend.

4. Version in the URL path

• Default: /v1/orders. Path versioning is visible, trivially testable in a browser or curl, and cache-friendly.
• Never version by incrementing resource names (/orders2).
• Media-type versioning (Accept: application/vnd.shop.v2+json) is the alternative for cases where the URL must stay frozen; note it and move on — it is harder to debug and most teams should not start there.
• Rules: additive changes (new fields, new endpoints) do not need a new version; breaking changes (renames, removed fields, changed semantics) do. Old versions get a documented sunset date, and Sunset/Deprecation response headers once one is set.

5. Use one error envelope everywhere

json
{
  "error": {
    "code": "validation_failed",
    "message": "quantity must be a positive integer",
    "details": [{"field": "quantity", "issue": "expected integer >= 1, got 0"}],
    "request_id": "req_9f3a2c1e"
  }
}

• code: stable, machine-readable snake_case clients can switch on. Never change a code's meaning; add a new code instead.
• message: human-readable, one sentence, no stack traces, no PII.
• details: array of field-level problems for 400/422; empty or omitted otherwise.
• request_id: unique per request, echoed in logs — this is how a client report turns into a server-side trace.
• 5xx responses keep message generic ("something went wrong") with the request_id as the only diagnostic.

Output Contract

When asked to design or review an API, produce:

1. The resource inventory (paths + methods) following the naming rules above.
2. A status-code callout per endpoint for success and the 2–3 most likely failures.
3. The pagination choice (offset or cursor) with the reason, plus the response shape.
4. The error envelope with one example code per failure mode.
5. The versioning decision (/v1/ default) and what counts as breaking.

When asked only to review, produce the checklist below with pass/fail per item and the offending endpoint.

Operating Rules

1. Cursor is the default pagination for anything user-facing or mutating; offset only for small, stable, random-access lists.
2. No 200-with-error-body, ever. No verbs in paths. No invented status codes.
3. Every 201 carries a Location header; every 429/503 carries Retry-After.
4. Error code values are a public contract — stable and documented.
5. Label example URLs as fictional (api.example.com) unless they point at a real, verified service.
6. Auth design is out of scope — see api-auth-patterns. GraphQL is out of scope — see graphql-basics.

Design review checklist

Run this against any existing API, endpoint by endpoint:

• [ ] All collection paths are plural nouns; no verbs in any path.
• [ ] Filtering/sorting are query params, not path segments.
• [ ] GETs have no side effects.
• [ ] POST creations support Idempotency-Key (or the API documents why not).
• [ ] Each endpoint's success code is 200/201/204 as appropriate; 201s include Location.
• [ ] No 200-with-error-body anywhere; failures use 4xx/5xx.
• [ ] 400 vs 422 split is consistent (malformed vs semantically invalid).
• [ ] 401 (who are you) vs 403 (not allowed) vs 404 (not found / hiding existence) are used correctly.
• [ ] 409 used for state conflicts (duplicates, stale versions), not 400.
• [ ] 429/503 include Retry-After.
• [ ] List endpoints paginate; the choice (offset/cursor) matches the access pattern; sort keys are stable with an id tie-breaker.
• [ ] Every error response matches the envelope (code, message, details, request_id); 5xx messages are generic.
• [ ] Version is in the path (/v1/); breaking-change policy is documented.