# name: designing-rest-apis description: Designs REST APIs with correct resource naming, HTTP method and status-code semantics, mandatory pagination, day-one versioning, and RFC 9457 problem+json errors, with OpenAPI as the source of truth. Use when the user asks to design, review, or refactor a REST API, define endpoints or routes, choose status codes, add pagination or versioning, or write an OpenAPI/Swagger spec. Do not use for GraphQL APIs (designing-graphql-apis), webhook delivery (designing-webhooks), or authentication mechanics (implementing-authentication).

# Designing REST APIs

# When to use / when NOT to use

• Use for: designing or reviewing REST endpoints, URL structure, status codes, pagination, versioning, error bodies, OpenAPI specs.
• Do NOT use for: GraphQL schemas → designing-graphql-apis; webhook delivery → designing-webhooks; login/tokens → implementing-authentication; rate-limit policy → limiting-request-rates.

# Core rules

1. Plural nouns, never verbs, in paths. Actions come from HTTP methods; non-CRUD actions become sub-resources.
   • ✅ POST /orders, POST /orders/42/cancellation
   • ❌ POST /createOrder, GET /getOrders
2. Method semantics are non-negotiable. GET is safe and cacheable; PUT replaces and is idempotent; PATCH partially updates; DELETE is idempotent (second call → 404 or 204, never 500). Never mutate on GET.
3. Status codes carry meaning — use the right one. 200 read/update, 201 + Location header on create, 204 no body, 400 malformed syntax, 401 unauthenticated, 403 unauthorized, 404 absent (also for hiding resources), 409 state conflict, 422 valid syntax but failed business validation, 429 rate limited, 500 only for genuine server faults.
   • ✅ 422 for "email already registered"
   • ❌ 200 {"success": false}
4. Every collection paginates from day one. Default limit=20, hard max limit=100; return cursor pagination (next_cursor) by default, offset only for small, static datasets.
5. Version from the first commit. Path prefix /v1/ is the default. A breaking change (removed/renamed field, changed type or semantics) requires /v2/; additive changes do not.
6. Errors are structured, uniform, and safe. Use RFC 9457 problem+json: type, title, status, detail, instance (+ per-field errors array for 422). Never leak stack traces, SQL, or internal class names.
7. The OpenAPI spec is the source of truth. Write or update the spec with every endpoint change; generated docs and clients follow the spec, not the code.
8. Filtering and sorting are query parameters with one convention. ?status=active&sort=-created_at (leading - = descending). Unknown parameters → 400, don't ignore silently.

# Workflow

1. List the resources (nouns) and their relationships before any URL exists.
2. Map each operation to method + path per rules 1–2; define request/response bodies.
3. Assign status codes per rule 3, including every failure path.
4. Add pagination, filtering, versioning per rules 4–5, 8.
5. Write the OpenAPI spec (or update it) and define the problem+json error schema once, referenced everywhere.
6. Validate: lint the spec (npx @redocly/cli lint openapi.yaml — install with npm i -g @redocly/cli if missing) and walk one full CRUD cycle checking each response code against rule 3. Fix and re-lint until clean.

# Edge cases & failure modes

• Long-running operations → 202 Accepted + status resource (GET /operations/{id}), never a 30 s blocking request.
• Bulk operations → dedicated resource (POST /orders/batch) returning per-item results with individual statuses (207-style body), not first-error-aborts.
• Retries on create → accept an Idempotency-Key header on POST; same key + same body → same response, no duplicate.
• Deprecating a field → mark deprecated: true in the spec and announce a sunset date; removal only in the next major version.

# References

Deeper patterns (pagination envelopes, problem+json schemas, OpenAPI skeleton): see references/patterns.md.