REST API Design

When to use

• The user needs write operations (create, payment, update) that clients can retry without duplicating side effects.
• The user is designing a new HTTP API and needs to model resources, choose verbs, and shape URLs.
• The user needs to pick correct HTTP status codes for success, client errors, and server errors on an API.

When NOT to use

• Do not apply REST resource-and-verb design when the interface is a GraphQL endpoint driven by a single schema and queries.
• Do not force REST resource modeling onto an internal, action-oriented RPC or command interface between trusted services.

Core guidance

• Model resources as plural nouns, actions as HTTP verbs — Name endpoints after resources using plural nouns (/orders, /orders/42) and express the action with the HTTP method, not in the path. Avoid verbs in URLs such as /createOrder or /getOrders.
• Match verbs to their safe and idempotent semantics — Use GET for safe reads, POST to create or run non-idempotent actions, PUT for a full idempotent replace, PATCH for a partial update, and DELETE to remove. Do not mutate state on GET.

Quick recipe

1. Name the resource as a plural noun and define its two base paths — the collection (/orders) and the item (/orders/{id}). (verify: The paths contain only nouns and identifiers, no verbs.)
2. Assign GET (list/read), POST (create → 201 + Location), PUT/PATCH (update), and DELETE (→ 204) to the paths, each returning the status code that matches its outcome. (verify: Each operation returns a code from the correct class for success and error.)
3. Validate the request body at the boundary, return 422 with a consistent problem-details error on failure, and serialize the resource through a response DTO so no internal fields leak. (verify: Invalid input yields a structured 422, and the success payload exposes only public fields.)

Best practices

• Return errors with a consistent JSON structure — ideally RFC 9457 problem details (type, title, status, detail) — so every endpoint reports failures the same way and clients can handle them uniformly
• For POST operations with real side effects (payments, order creation), accept an Idempotency-Key header, store the first result keyed by it, and return that same result on any retry with the same key
• Return 200 for a successful read or update, 201 with a Location header on create, 204 for a body-less success, 400/422 for invalid input, 401/403 for auth failures, 404 for a missing resource, and 409 for a conflict

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Returning 200 with an error in the body — Returning HTTP 200 while signaling failure only through a body field hides errors from clients and monitoring. Fix: Set the status code to the real outcome (4xx for client errors, 5xx for server faults) and put detail in the body.
2. A GET endpoint that changes state — Performing a write inside a GET handler (for example GET /orders/42/cancel) breaks the safe-method contract. Fix: Move the mutation to POST/PATCH/DELETE on the resource and keep GET strictly read-only.
3. Collection endpoints that return every row — A GET /orders that returns the entire table with no default limit degrades as data grows and can exhaust memory. Fix: Apply a sane default and maximum page size and return paginated results; see api/pagination for the page-model choices.

Version notes

• RFC 9457 supersedes RFC 7807 for problem details (PHP >=8.1) — Use the RFC 9457 problem-details media type (application/problem+json) for error bodies; it obsoletes RFC 7807 but keeps the same field names, so existing 7807 payloads remain valid.

Security

• Validate input and authorize every resource access — Validate and type every request field at the boundary before use, and authorize the caller against the specific resource id — do not rely on an unguessable id as access control (no insecure direct object references).

Testing

• Activation and decision behavior are verified in eval/scenarios/api/rest-design.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: api/openapi, api/pagination, api/versioning, security/sql-injection-prevention