REST API Design Best Practices: A Practical Guide

What and Why

REST APIs are the lingua franca of web backends. A well-designed API is easy to learn, hard to misuse, and stable across years. A poorly designed one wastes integration time, hides bugs, and gets rewritten every two years.

The good news: a handful of conventions cover 90% of API design. They are boring on purpose.

Mental Model

REST treats your domain as a set of resources, each addressable by a URL. HTTP verbs act on those resources: GET reads, POST creates, PUT and PATCH update, DELETE removes. Status codes describe the outcome. Everything else is convention.

If you find yourself inventing custom verbs in the URL (/createOrder, /getUser), step back. The verb belongs in the HTTP method.

Architecture

GET    /orders          -> list orders
POST   /orders          -> create order
GET    /orders/{id}     -> read one order
PATCH  /orders/{id}     -> partial update
DELETE /orders/{id}     -> delete order
GET    /orders/{id}/items -> nested resource

Use plural nouns for collections. Use IDs that are stable and globally unique (UUIDs or prefixed IDs like ord_abc123). Avoid leaking database internals like auto-increment integers.

Group related resources under a parent only when they have no meaning outside that parent. Otherwise expose them at the top level and reference the parent via a query parameter.

Trade-offs

Strict REST is great for CRUD. It is awkward for actions (“approve this PR,” “send a reset email”). Many teams add /orders/{id}/cancel as a POST endpoint and accept that REST is a guide, not a rulebook.

Hypermedia (HATEOAS) is theoretically clean but rarely adopted. Most teams ship documented URLs and accept the coupling for the sake of clarity.

Verbose responses are kind to humans but heavy on the wire. Consider sparse fieldsets (?fields=id,name) for clients that care.

Practical Tips

Use 200, 201, 204, 400, 401, 403, 404, 409, 422, and 429 deliberately. Most APIs need only this small set. Reserve 5xx for actual server faults.

Paginate everything by default. Cursor-based pagination handles inserts gracefully; offset pagination is simpler but degrades on deep pages. Always include a stable sort.

Version at the URL (/v1/orders) or via a header. URL versioning is easier to test and route. Bump only on breaking changes.

Validate input early and return field-level errors. A response like { errors: [{ field: "email", message: "invalid" }] } saves clients hours of debugging.

Document the API as code with OpenAPI. Generate clients and docs from the same source so they cannot drift.

Wrap-up

Good REST design is a discipline of restraint. Stick to nouns, verbs, and status codes. Paginate, validate, and version explicitly. Resist the urge to be clever. The result is an API that consumers actually enjoy, which is the rarest and most valuable property an API can have.