REST API Design
Purpose
Design a consistent, predictable REST surface: resources, verbs, status codes, pagination, versioning, and response conventions — recorded as a contract clients can rely on (api-contracts).
When to Use
- When defining or extending a REST API's endpoints.
- Not for GraphQL (
graphql-api-design) or internal layering (backend-api-architecture).
Inputs
- Domain model and client needs (which apps consume this — web/mobile).
- Auth model (
backend-authentication, backend-authorization).
Discovery Questions
- What resources exist, and what are their relationships/sub-resources?
- Which endpoints return collections — how large can they grow?
- Which operations are unsafe to retry (payments, sends) and need idempotency keys?
- Who consumes this API, and what versioning tolerance do they have?
Responsibilities
- Name resources as plural nouns (
/orders, /orders/{id}/items); actions that don't fit CRUD become explicit sub-resources or verbs done deliberately (/orders/{id}/cancel), not scattered RPC.
- Map methods correctly: GET (safe), POST (create/process), PUT/PATCH (replace/partial), DELETE — with correct status codes (200/201/204, 400/401/403/404/409/422, 429, 5xx).
- Require pagination on every collection (cursor-based for growing data; offset acceptable for small, stable sets), plus filtering/sorting conventions.
- Define one error response shape (
backend-error-handling) and one envelope convention — used everywhere.
- Plan versioning (URL prefix or header) and what counts as a breaking change (
api-contracts).
- Mark idempotent operations; require idempotency keys for unsafe-to-retry POSTs.
- Document the unit as it is built — one file per resource under
docs/<app>/api/ (../../application-documentation).
Required Workflow
- List resources + relationships from the domain model.
- Define endpoints per resource with methods, status codes, auth requirements.
- Fix pagination/filter/sort conventions once, apply everywhere.
- Define the error shape + versioning policy.
- Record the design in the API contract.
Decision Rules
- 401 = unauthenticated, 403 = unauthorized, 404 = also acceptable for existence-hiding (
ownership-authorization) — pick per resource and be consistent.
- Unbounded collections are defects: paginate from day one.
- Prefer 422 for semantic validation failures, 400 for malformed requests — and document the choice.
- Breaking changes require a new version; additive changes don't.
Rules
- Every endpoint carries an auth requirement annotation (public / authenticated / role / ownership).
- Conventions are decided once and recorded; per-endpoint improvisation is a defect.
- Design output is the contract, not handler code.
Anti-Patterns
- Verbs in resource paths as the norm (
/getOrders).
- 200-with-error-body responses.
- Collections without pagination "because it's small now."
- Different error shapes per endpoint.
- Encoding authorization in the client's knowledge of hidden endpoints.
Validation Checklist
Definition of Done
A recorded endpoint design — resources, methods, status codes, conventions, auth annotations — registered in the API contract and consistent across the surface.
Related Skills
api-contracts, graphql-api-design, backend-api-architecture, backend-validation, backend-error-handling, backend-authorization, rate-limiting, ../../application-documentation.
Related Knowledge
../../../knowledge/ (domain model, client constraints).
Related References
../../../references/backend/api/ (endpoint conventions, when populated).
Context Loading Guidance
- Requires: domain model, consumer list, auth model summary.
- Does not require: implementation code, database internals.
- May load:
api-contracts, backend-error-handling.
- Stop when: the endpoint design is recorded in the contract.
Token Efficiency Guidance
Design as an endpoint table (path, method, auth, status codes); state conventions once instead of repeating per endpoint.
1---2name: rest-api-design3description: Use to design a REST API surface — resource naming, HTTP methods and status codes, pagination, filtering, versioning, idempotency, and consistent response shapes. Produces an endpoint design, not code.4---56# REST API Design78## Purpose910Design a consistent, predictable REST surface: resources, verbs, status codes, pagination, versioning, and response conventions — recorded as a contract clients can rely on (`api-contracts`).1112## When to Use1314- When defining or extending a REST API's endpoints.15- **Not** for GraphQL (`graphql-api-design`) or internal layering (`backend-api-architecture`).1617## Inputs1819- Domain model and client needs (which apps consume this — web/mobile).20- Auth model (`backend-authentication`, `backend-authorization`).2122## Discovery Questions2324- What resources exist, and what are their relationships/sub-resources?25- Which endpoints return collections — how large can they grow?26- Which operations are unsafe to retry (payments, sends) and need idempotency keys?27- Who consumes this API, and what versioning tolerance do they have?2829## Responsibilities3031- Name resources as **plural nouns** (`/orders`, `/orders/{id}/items`); actions that don't fit CRUD become explicit sub-resources or verbs done deliberately (`/orders/{id}/cancel`), not scattered RPC.32- Map methods correctly: GET (safe), POST (create/process), PUT/PATCH (replace/partial), DELETE — with correct status codes (200/201/204, 400/401/403/404/409/422, 429, 5xx).33- Require **pagination on every collection** (cursor-based for growing data; offset acceptable for small, stable sets), plus filtering/sorting conventions.34- Define one **error response shape** (`backend-error-handling`) and one envelope convention — used everywhere.35- Plan versioning (URL prefix or header) and what counts as a breaking change (`api-contracts`).36- Mark idempotent operations; require idempotency keys for unsafe-to-retry POSTs.37- Document the unit as it is built — one file per resource under `docs/<app>/api/` (`../../application-documentation`).3839## Required Workflow40411. List resources + relationships from the domain model.422. Define endpoints per resource with methods, status codes, auth requirements.433. Fix pagination/filter/sort conventions once, apply everywhere.444. Define the error shape + versioning policy.455. Record the design in the API contract.4647## Decision Rules4849- 401 = unauthenticated, 403 = unauthorized, 404 = also acceptable for existence-hiding (`ownership-authorization`) — pick per resource and be consistent.50- Unbounded collections are defects: paginate from day one.51- Prefer 422 for semantic validation failures, 400 for malformed requests — and document the choice.52- Breaking changes require a new version; additive changes don't.5354## Rules5556- Every endpoint carries an auth requirement annotation (public / authenticated / role / ownership).57- Conventions are decided once and recorded; per-endpoint improvisation is a defect.58- Design output is the contract, not handler code.5960## Anti-Patterns6162- Verbs in resource paths as the norm (`/getOrders`).63- 200-with-error-body responses.64- Collections without pagination "because it's small now."65- Different error shapes per endpoint.66- Encoding authorization in the client's knowledge of hidden endpoints.6768## Validation Checklist6970- [ ] Resources named consistently; relationships mapped.71- [ ] Methods + status codes correct per endpoint.72- [ ] Pagination/filter/sort conventions fixed and applied.73- [ ] Single error shape; versioning policy defined.74- [ ] Idempotency handled for unsafe retries.75- [ ] Auth requirement annotated per endpoint.7677## Definition of Done7879A recorded endpoint design — resources, methods, status codes, conventions, auth annotations — registered in the API contract and consistent across the surface.8081## Related Skills8283`api-contracts`, `graphql-api-design`, `backend-api-architecture`, `backend-validation`, `backend-error-handling`, `backend-authorization`, `rate-limiting`, `../../application-documentation`.8485## Related Knowledge8687`../../../knowledge/` (domain model, client constraints).8889## Related References9091`../../../references/backend/api/` (endpoint conventions, when populated).9293## Context Loading Guidance9495- **Requires:** domain model, consumer list, auth model summary.96- **Does not require:** implementation code, database internals.97- **May load:** `api-contracts`, `backend-error-handling`.98- **Stop when:** the endpoint design is recorded in the contract.99100## Token Efficiency Guidance101102Design as an endpoint table (path, method, auth, status codes); state conventions once instead of repeating per endpoint.
ahtishamshahzad