REST API Design Principles That Age Well
A well-designed REST API is predictable and hard to break. Learn resources, methods, status codes, versioning, and pagination.
By Velloreth
Resources, not actions
Model the API around nouns, and use the HTTP method for the verb.
GET /articles # list
POST /articles # create
GET /articles/42 # read
PUT /articles/42 # replace
PATCH /articles/42 # partial update
DELETE /articles/42 # delete
Avoid verbs in the path. /getArticle?id=42 is an RPC style, not REST. The method already expresses the operation.
Nest for a genuine relationship, but not deeply.
GET /articles/42/comments # comments of an article
GET /comments/7 # a comment directly
Two levels is usually enough. A path like /users/1/posts/2/comments/3/likes is hard to read and hard to route.
Methods and their semantics
| Method | Safe | Idempotent | Body |
|---|---|---|---|
| GET | Yes | Yes | No |
| POST | No | No | Yes |
| PUT | No | Yes | Yes |
| PATCH | No | No | Yes |
| DELETE | No | Yes | No |
Safe means no side effect. Idempotent means repeating it has the same effect as doing it once.
Idempotency matters for retries. A client that times out does not know whether the request succeeded, so it retries. A PUT or DELETE is safe to retry; a POST is not, which is why a create endpoint often accepts an idempotency key.
Status codes
Use the code to communicate the outcome.
| Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created (with a Location header) |
| 204 | No Content (a successful delete) |
| 400 | Bad Request (malformed) |
| 401 | Unauthorized (not authenticated) |
| 403 | Forbidden (authenticated but not allowed) |
| 404 | Not Found |
| 409 | Conflict (a duplicate) |
| 422 | Unprocessable Entity (validation failed) |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Do not return 200 with an error in the body. A client, a proxy, and a monitoring system all read the status code, and a 200 tells them the request succeeded.
401 versus 403. 401 means the request lacks valid credentials; 403 means the credentials are valid but the action is not permitted. The distinction matters for a client that should re-authenticate on 401 but not on 403.
Error responses
A consistent error shape makes a client’s error handling simple.
{
"error": {
"code": "validation_failed",
"message": "The request body is invalid.",
"details": [
{ "field": "email", "message": "must be a valid email address" }
]
}
}
Include a machine-readable code so the client can branch on it without parsing the message.
Include the field errors for a validation failure, so the client can highlight the right input.
Do not leak internals. A stack trace or a database error message in a 500 response is an information disclosure.
Versioning
Version from the start, because a breaking change without a version breaks every client.
GET /v1/articles
A version in the path is the most common. It is easy to route, easy to document, and easy to test in a browser.
A version in a header is more correct in theory, because the URL identifies the resource and the version is a representation concern. In practice it is harder to test and debug.
What counts as breaking: removing a field, changing a type, renaming a field, adding a required parameter, or changing the meaning of a value. Adding an optional field or a new endpoint is not breaking.
Pagination
Paginate every collection. An unbounded list is a performance problem waiting to happen.
Offset pagination:
GET /articles?limit=20&offset=40
Simple, and it supports jumping to a page. The problem is drift: if an item is inserted while a client pages, an item can be skipped or repeated.
Cursor pagination:
GET /articles?limit=20&cursor=eyJpZCI6NDJ9
The cursor encodes the position, so the page is stable even when items are added. It scales better, because the database can use an index rather than counting rows.
Always return the total and the next cursor:
{
"data": [...],
"pagination": {
"next_cursor": "eyJpZCI6NjJ9",
"has_more": true
}
}
Cap the limit. A client that asks for a million rows should get a 400, not a timeout.
Filtering, sorting, and search
GET /articles?status=published&sort=-published_at&q=rest
Use a consistent convention. A leading - for descending is common and readable.
Whitelist the sortable fields. A client that can sort by any column can trigger an expensive query.
Document the filters. An undocumented filter is a support ticket.
Naming and casing
Use plural nouns for collections: /articles, not /article.
Use kebab-case in the path and snake_case or camelCase in the body, consistently. The choice matters less than the consistency.
Be consistent with the timestamp format. ISO 8601 in UTC is the safe default.
Authentication
Use a bearer token in the Authorization header.
Authorization: Bearer <token>
Do not put a token in the query string. It ends up in logs, in browser history, and in a referrer header.
Return 401 with a WWW-Authenticate header when the token is missing or invalid.
Practical guidance
- Model resources, not actions.
- Use the method for the verb.
- Return the correct status code.
- Use a consistent error shape.
- Version from the start.
- Paginate every collection.
- Cap the page size.
- Whitelist sortable fields.
- Make the API idempotent where it can be.
- Do not leak internals in an error.
For the related guides, see http-status-codes-explained and rest-api-rate-limiting. For the broader context, api-authentication-methods and json-vs-yaml-vs-toml.
Quotable summary
Model a REST API around resources rather than actions, and use the HTTP method to express the operation, so the path holds nouns and the method holds the verb. Use the status code to communicate the outcome and never return 200 with an error in the body, because a client, a proxy, and a monitoring system all read the status code. Version the API from the start, because a breaking change without a version breaks every client, and paginate every collection, because an unbounded list is a performance problem waiting to happen. Make the API idempotent where it can be, so a retry after a timeout is safe, and use a consistent error shape with a machine-readable code so a client can branch on it without parsing the message.