REST API Design

REST (Representational State Transfer) is an architectural style defined by Roy Fielding in 2000, built on six constraints: client-server, statelessness, cacheability, uniform interface, layered system, and optional code-on-demand. The Richardson Maturity Model grades APIs from Level 0 (single endpoint, RPC-style) through Level 1 (resources), Level 2 (HTTP verbs + status codes), to Level 3 (HATEOAS — hypermedia links in responses). Most production APIs target Level 2; Level 3 HATEOAS adds discoverability but at the cost of client complexity.

Key Points

• Resource naming: use nouns not verbs (/orders not /getOrders), plurals (/users/{id}), and hierarchical nesting for owned resources (/users/{id}/orders) — max 2 levels of nesting to avoid deep URL complexity.
• HTTP verbs enforce semantic clarity: GET (read), POST (create), PUT (full replace), PATCH (partial update), DELETE (remove); violating verb semantics (GET with side effects) breaks caching and idempotency guarantees.
• Status codes: 200 OK (success with body), 201 Created (POST success, include Location header), 204 No Content (DELETE success), 400 Bad Request (client error, include error detail), 404 Not Found, 409 Conflict, 422 Unprocessable Entity (validation), 429 Too Many Requests, 503 Service Unavailable.
• HATEOAS example: a payment response includes _links.refund.href="/payments/123/refunds" — clients discover available actions from responses rather than hardcoding URLs.
• Content negotiation: Accept: application/json, application/xml; Content-Type: application/json; API should return 406 Not Acceptable if requested format is unsupported.
• Idempotency: GET, PUT, DELETE, HEAD are idempotent (repeating the request has the same effect); POST is not; PATCH may or may not be depending on implementation.
• Resource representation vs entity: the resource /users/42 may return different shapes depending on Accept header or query parameter (?fields=id,name) — use sparse fieldsets for bandwidth-sensitive clients.
• OpenAPI 3.x (Swagger) spec is the contract: define paths, operations, request/response schemas, security schemes, and error models; generate client SDKs and documentation automatically.