REST API Design Best Practices
A well-designed REST API is predictable, easy to document, and pleasant for other developers to integrate with. Over years of building backend services and integrations, these are the practices I come back to on every project.
1. Model Resources, Not Actions
URLs should represent resources (nouns), and HTTP methods should represent the action (verbs):
GET /orders # list orders
GET /orders/42 # get one order
POST /orders # create an order
PATCH /orders/42 # update an order
DELETE /orders/42 # delete an order
Avoid verbs in the path like /getOrder or /createOrder — the HTTP method already tells you that.
2. Use Consistent, Predictable Responses
Pick one envelope shape and stick to it across every endpoint:
{
"data": { "id": 42, "status": "paid" },
"meta": { "requestId": "abc-123" }
}
For errors, always return the same shape so clients can handle failures generically:
{
"error": {
"code": "ORDER_NOT_FOUND",
"message": "Order 42 does not exist"
}
}
3. Use HTTP Status Codes Correctly
200success,201created,204no content400bad request (client sent something invalid)401unauthenticated,403forbidden404not found,409conflict422validation failed500unexpected server error
Returning 200 for every response, with the real status buried in the body, forces every client to parse the body just to know if something worked.
4. Version Your API Early
Even a simple /v1/ prefix in the URL (or an Accept header version) gives you room to make breaking changes later without breaking existing clients.
5. Support Pagination, Filtering, and Sorting Consistently
GET /orders?status=paid&sort=-createdAt&page=2&limit=20
Document the defaults (what happens with no limit?) and cap the maximum page size so a client can't accidentally request your entire database in one call.
6. Make Authentication Explicit
Use the Authorization header with a bearer token rather than custom headers or query-string tokens, which end up logged in server access logs and browser history.
7. Document With Examples
A schema is useful, but a request/response example for the happy path and at least one error case saves far more integration time than a field-by-field reference alone. Tools like OpenAPI/Swagger let you keep the spec and the documentation in sync.
Summary
None of these practices are complicated on their own, but skipping any of them tends to show up later as inconsistent client code, confusing error handling, or APIs that are impossible to evolve without breaking someone. Decide on these conventions before you write the first endpoint, not after the third one disagrees with the first.
