REST API Design

5.4.1Definition

REST (Representational State Transfer) is an architectural style for designing APIs around resources — nouns like /users or /orders — manipulated through standard HTTP methods (GET, POST, PUT, PATCH, DELETE). A well-designed REST API is predictable enough that a developer can guess an endpoint's shape without reading documentation.

5.4.2Why It Exists

Before REST conventions standardized, every API invented its own verbs and structures, forcing every integration to be learned from scratch. REST exists to make APIs predictable by reusing HTTP's existing semantics (a method and a status code) rather than inventing new ones, dramatically lowering the cost of a new client integrating with a backend it has never seen before.

5.4.3Core Conventions

• Resource-based URLs — /orders/42, not /getOrder?id=42; the URL names a thing, the HTTP method names the action.
• Correct status codes — 200 (success), 201 (created), 400 (client error), 401 (unauthenticated), 403 (unauthorized), 404 (not found), 500 (server error) — used consistently rather than always returning 200 with an error message in the body.
• Versioning — /v1/orders or a version header, so breaking changes don't silently break every existing client.
• Pagination — for any list endpoint that could grow unbounded, returning a page at a time rather than the entire table.

5.4.4Common Mistakes

• Verbs in URLs. /createUser or /deleteOrder instead of using the HTTP method itself to express the action on a noun-based URL.
• Always returning HTTP 200. Encoding every error as a 200 response with an {"error": true} body, breaking standard HTTP tooling, caching, and client error-handling that relies on status codes.
• No pagination on list endpoints, which works fine in testing with ten rows and falls over in production with ten million.
• Breaking changes shipped with no version bump, silently breaking every existing integration the moment the change deploys.

5.4.5Best Practices

• Design URLs around resources and nesting (/users/12/orders), reserving query parameters for filtering and pagination.
• Return consistent, structured error bodies alongside the correct HTTP status code.
• Document the API with a machine-readable spec (OpenAPI) so client teams and tools can generate integrations automatically.