API design best practices
The conventions that make an API feel obvious instead of hostile.
A well-designed HTTP API is predictable: resources are nouns, verbs are HTTP methods, status codes mean what they say, and the shape of a response you've never seen is one you can already guess. Layer on versioning, pagination, filtering, idempotency, rate limits, consistent errors and real docs, and clients can build against you without reading your mind.
Resource-oriented naming
Model your API around resources — things — named as plural nouns: /users, /orders, /orders/42/items. Avoid stuffing verbs into paths like /getUser or /createOrder, because the action belongs in the HTTP method, not the URL. A consistent, hierarchical noun structure means a client who has seen /users can correctly guess /products without documentation.
Correct verbs & status codes
Let the HTTP method express intent: GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes. Pair each response with the status code that actually describes it — 200/201/204 for success, 400/401/403/404/409 for caller mistakes, 500/503 for your own. Returning a 200 with an error buried in the body is the single most common way to make an API painful to consume.
Versioning
The moment a real client depends on you, your contract is frozen for them, so you need a way to change without breaking. Put a version in the path (/v1/users) or a header, and treat any incompatible change — removing a field, renaming, tightening validation — as requiring a new version. This lets old clients keep working on v1 while new clients move to v2 on their own schedule.
Pagination, filtering & sorting
Never return an unbounded collection: a /users endpoint that grows to a million rows will eventually time out and blow up memory on both ends. Page results (cursor- or offset-based) and expose filtering, sorting and field selection through query params like ?status=active&sort=-created_at&fields=id,name. This pushes work to the database's indexes and lets clients ask for exactly what they need.
Idempotency
Networks fail and clients retry, so a write must be safe to send twice. GET, PUT and DELETE are naturally idempotent; POST is not, which is why you accept an Idempotency-Key header and de-duplicate on it, guaranteeing that a retried 'create payment' doesn't charge twice. Designing for safe retries is what separates a robust API from one that double-books under load.
Rate limiting & consistent errors
Protect the backend from abuse and runaway clients with rate limits, signaled via 429 and headers like X-RateLimit-Remaining and Retry-After so callers can back off gracefully. Just as important, return every error in one predictable envelope — a machine-readable code, a human message, and enough detail to act on — so clients write error handling once instead of per endpoint. Consistency here is what makes automated retries and alerting possible.
HATEOAS & great docs
At the most mature level, responses include links to related actions (HATEOAS), so a client can discover what it can do next from the payload itself rather than hard-coding URLs. In practice, few APIs go fully hypermedia, but all of them live or die on documentation: accurate reference, real request/response examples, auth instructions and an OpenAPI spec. The best-designed endpoint is worthless if nobody can figure out how to call it.
Why design conventions matter
An API is a contract, and its real users are other developers who will build against it — often without ever talking to you. That makes API design a user-experience problem more than a coding problem. A predictable API is one where, after learning a handful of endpoints, a developer can correctly guess the rest: the naming, the verbs, the error shape, and the pagination all follow the same rules everywhere. An inconsistent API forces the caller to memorize every endpoint as a special case, which is slow, error-prone, and quietly expensive for everyone downstream.
The conventions in this guide are not arbitrary style preferences. They are the accumulated answers to problems every large API eventually hits: how do you change without breaking existing clients, how do you keep a growing collection from timing out, how do you make a retry safe, and how do you fail in a way the caller can actually handle. Follow them and clients integrate in an afternoon. Ignore them and you generate a permanent stream of support tickets, brittle client code, and v1 mistakes you can never take back.
Resources, verbs, and status codes
The foundation is resource orientation. You model your API as a set of resources — the nouns of your domain, like users, orders, and invoices — and you name them with plural nouns in a hierarchy: /users, /users/42, /users/42/orders. The action is never in the path. You do not build /createUser or /getUserOrders; you let the HTTP method express intent against the noun.
The verbs map cleanly to operations:
GETreads a resource or collection and must have no side effects.POSTcreates a new resource under a collection.PUTreplaces a resource wholesale;PATCHupdates part of it.DELETEremoves it.
Equally important is returning the right status code. A 2xx means success (200 OK, 201 Created, 204 No Content). A 4xx means the caller made a mistake (400 bad input, 401 not authenticated, 403 not allowed, 404 not found, 409 conflict). A 5xx means your server failed. The cardinal sin — depressingly common — is returning 200 OK with an error hidden in the body. It defeats every generic HTTP client, every proxy, and every monitoring tool, all of which reasonably assume 200 means it worked.
Evolving safely: versioning and collections
As soon as a real client depends on your response shape, that shape is frozen for them. Removing a field, renaming one, or tightening validation is a breaking change that will crash integrations in production. Versioning is how you keep moving anyway. The most common approach is a version prefix in the path (/v1/users), which is explicit and easy to route; header-based versioning is cleaner in theory but harder to test and cache. The rule is simple: additive changes (new optional fields, new endpoints) can go into the current version, but anything incompatible earns a new one, so old clients keep running on v1 while new work targets v2.
The other thing that quietly breaks is any collection that can grow. A GET /users that returns every row is a time bomb: fine with a hundred users, catastrophic with a million. Always paginate. Offset pagination (?page=3&limit=50) is easy but drifts when data changes underneath it; cursor pagination (?after=<token>) is stable and scales better. Alongside paging, expose filtering, sorting, and field selection through query parameters — ?status=active&sort=-created_at&fields=id,name — so clients fetch exactly what they need and the work pushes down onto your database's indexes instead of into application memory.
Robustness: idempotency, rate limits, and errors
Distributed systems retry. A client sends a request, the network hiccups before the response arrives, and the client — not knowing whether the write succeeded — sends it again. Idempotency is the property that sending the same request twice has the same effect as sending it once. GET, PUT, and DELETE are naturally idempotent. POST is not, which is why serious APIs accept an Idempotency-Key header: the server records the key on first use and returns the original result on any retry, so a double-submitted "create payment" charges the customer exactly once.
Rate limiting protects your backend from abuse, runaway loops, and one noisy client starving everyone else. Signal it with the 429 Too Many Requests status and headers like X-RateLimit-Remaining and Retry-After so well-behaved clients can back off automatically instead of hammering you. And when anything goes wrong, fail consistently: every error should use one envelope with a stable machine-readable code, a human-readable message, and enough context to act on. When errors have a uniform shape, clients write their handling, logging, and alerting once — instead of reverse-engineering a different failure format for every endpoint.
Discoverability, docs, and the practical bar
At the top of the maturity ladder is HATEOAS (Hypermedia As The Engine Of Application State), where responses embed links to the actions available next — a paid order includes a link to its refund endpoint, a paginated list includes next and prev links. In theory this lets clients navigate your API without hard-coding URLs. In practice, full hypermedia is rare because most clients find it easier to code against known paths, but the lightweight version — returning pagination and related-resource links — is genuinely useful and cheap to add.
What no successful API skips is documentation. The best-designed endpoint on earth is useless if a developer can't figure out how to call it. Good docs mean an accurate reference for every endpoint, real request and response examples (not just schemas), clear authentication instructions, and ideally a machine-readable OpenAPI specification that can generate client SDKs and interactive explorers automatically.
Pulling it together: design nouns and verbs first, return honest status codes, version before you need to, paginate everything that grows, make writes safe to retry, rate-limit and fail consistently, and document relentlessly. None of these are exotic. Their power is cumulative — an API that follows all of them feels obvious, and "obvious" is the highest compliment an integration developer can pay you.
Model resources as plural nouns (/users, /orders/42) and let HTTP verbs — GET, POST, PUT, PATCH, DELETE — carry the action.
Return the correct status code: 2xx success, 4xx caller error, 5xx server error; never wrap an error in a 200.
Version the contract (/v1) so you can evolve without breaking existing clients, and paginate every collection that can grow.
Support filtering, sorting and field selection via query params, and make writes idempotent so retries are safe.
Rate-limit to protect the backend, return errors in one consistent envelope, and document everything with real examples.
Quick quiz
Where should the action live in a REST-style API?
Why accept an Idempotency-Key on a POST that creates a payment?
What is a REST API
The architectural style that made the web's APIs feel like the web itself.
REST vs GraphQL
Two ways to shape an API — resources and endpoints, or one flexible query.
Ways to improve API performance
Seven levers that turn a sluggish endpoint into a fast one.
Common HTTP status codes
Three digits that tell you, at a glance, exactly how a request went.