REST Endpoint Conventions

Reviews or designs an HTTP API surface so the paths and response codes match what other REST clients expect. A capable model knows REST but does not apply it by default: it will accept a verb in the path, return 200 where the protocol wants 201/204, reach for 400 on a conflict, and nest resources three deep. This skill pins the conventions so the surface is predictable and self-consistent.

Out of scope (a sibling owns each): how to paginate or filter a list, GraphQL schema shape, and query performance.

When to Activate

• Review these endpoint paths / status codes before we ship
• What should this route be called?
• What should this endpoint return on success?
• Sign off on this new API surface
• A teammate proposed a route and I'm not sure it's idiomatic

Path naming

1. Resources are nouns, never verbs. The HTTP method already carries the verb. POST /orders creates; the path is the thing, not the action. Reject POST /createOrder, GET /getOrder, POST /order/delete.
2. Plural collections. A collection is /orders; a member is /orders/{id}. Not /order/{id}.
3. kebab-case segments. Multi-word segments use hyphens, lowercase: /user-profiles, not /userProfiles or /user_profiles.
4. Nesting at most two levels deep. Express one containment relationship, e.g. /orders/{id}/line-items. If a child has its own globally unique id, address it at the top level (/line-items/{id}) instead of /orgs/{id}/orders/{id}/line-items/{id}. Deep hierarchies are brittle and hard to route.
5. The method must match the effect. A read is GET and must not change state; a state change is POST/PUT/PATCH/DELETE. Never mutate on GET (GET /orders/{id}/cancel is wrong — use POST /orders/{id}/cancellation or DELETE).
6. A non-CRUD action is a sub-resource, scoped under its owner. To publish a document, POST /documents/{id}/publication (or a state transition on the resource) — not a top-level verb route like POST /publishDocument.

Status codes

Return the specific code for the outcome, not a generic 200/400.

| Situation | Code | Notes | |---|---|---| | Created a new resource | 201 Created | Return the resource; set a Location header to its URL. Not 200. | | Succeeded with no body to return (delete, some updates) | 204 No Content | Empty body. Not 200 with {}. | | Read / updated an existing resource, returning it | 200 OK | PUT/PATCH that updates returns 200, not 201 (201 only when it creates). | | Request accepted for async processing, not yet done | 202 Accepted | Use when work is queued, not completed inline. | | Body is well-formed but fails validation rules | 422 Unprocessable Entity | Reserve 400 for malformed/unparseable requests. | | Violates a uniqueness or state constraint (duplicate, already-taken) | 409 Conflict | A duplicate email is a conflict, not a 400. | | Caller is authenticated but not allowed, and the resource's existence is not secret | 403 Forbidden | The resource exists; the action is denied. | | Resource does not exist, or you must not reveal that it exists to this caller | 404 Not Found | Prefer 404 over 403 when confirming existence itself would leak (e.g. another tenant's record). | | Method not supported on this path | 405 Method Not Allowed | Include an Allow header. |

Error body

Every error response uses one consistent JSON shape across the whole API — do not let different endpoints invent their own. A workable default:

json
{ "error": { "code": "order_not_found", "message": "No order with id 42", "details": [] } }

A stable machine-readable code, a human message, and optional structured details (e.g. per-field validation errors). Pick a shape once; apply it everywhere. Success and error responses should be distinguishable without guessing.

Output

When reviewing, report each deviation as: the path or response, what convention it breaks, and the corrected form. Confirm the parts that are already correct so the reader knows they were checked.

| Endpoint | Issue | Fix | |---|---|---| | POST /createOrder | verb in path | POST /orders | | delete returns 200 {} | wrong success code | 204 No Content | | duplicate email → 400 | wrong error code | 409 Conflict |