RESTAPIDesign
title: REST API Design Best Practices type: technique created: 2026-05-21 last_updated: 2026-05-21 related: ["radar/techniques/ScriptToProduct", "radar/techniques/StructuredPromptDrivenDevelopment"] sources: ["https://github.com/stickfigure/blog/wiki/How-to-%28and-how-not-to%29-design-REST-APIs"] radar_quadrant: Techniques radar_ring: Adopt radar_position: inner
A set of established design principles for HTTP/REST APIs covering resource naming, HTTP method semantics, error response structure, versioning, authentication, and pagination — documented as actionable dos and don'ts.
The source document (Jeff Schnitzer's GitHub Wiki) covers the most consequential design decisions:
Resource naming. Use plural nouns for collections (/users, /orders). Avoid verbs in paths — the HTTP method carries the action. Nest resources only when the child cannot exist without the parent.
HTTP method semantics. GET must be idempotent and safe. POST creates or triggers non-idempotent operations. PUT replaces; PATCH modifies. DELETE is idempotent. Misusing POST for read operations and GET for mutations breaks caching and proxy behaviour.
Error responses. Return structured JSON bodies for all errors, not just 2xx responses. Include a machine-readable code field and a human-readable message. Do not rely solely on HTTP status codes — 400 is insufficient context for a client to take action.
Versioning. Version in the URL (/v1/) not in headers. Header versioning complicates caching and is harder to test manually. Start versioning at v1 from day one; retrofitting versioning is costly.
Authentication. Use Bearer tokens over Basic Auth. Never put credentials in query strings — they appear in server logs and browser history.
Pagination. Use cursor-based pagination, not offset-based. Offset pagination produces inconsistent results when the underlying dataset changes between pages. Return a next_cursor in the response envelope.
| Anti-pattern | Problem |
|---|---|
| Returning 200 for errors with an error body | Breaks HTTP client error detection |
Deeply nested resources (/a/b/c/d) |
Creates tight coupling and brittle client URLs |
| Non-idempotent GET endpoints | Breaks caching, proxies, and browser prefetch |
| Exposing database IDs in URLs | Leaks schema and enables enumeration attacks |
| Inconsistent field naming (camelCase vs snake_case) | Increases client integration friction |
REST API Design Best Practices sit in the Adopt ring of the Techniques quadrant, at inner position. The principles described are widely established and taught in every major API design guide. The stickfigure/blog wiki is a high-signal reference document distilling consensus best practices into a single, opinionated source. No novel tooling required. Inner Adopt reflects that these patterns should be applied by default in any new API project without further evaluation; deviation requires explicit justification.
