Skip to content
Velloreth
Programming 5 min read

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

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

MethodSafeIdempotentBody
GETYesYesNo
POSTNoNoYes
PUTNoYesYes
PATCHNoNoYes
DELETENoYesNo

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.

CodeMeaning
200OK
201Created (with a Location header)
204No Content (a successful delete)
400Bad Request (malformed)
401Unauthorized (not authenticated)
403Forbidden (authenticated but not allowed)
404Not Found
409Conflict (a duplicate)
422Unprocessable Entity (validation failed)
429Too Many Requests
500Internal 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.

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.

Frequently asked questions

What makes an API RESTful?
Resources identified by URLs, standard HTTP methods for operations, stateless requests, and a representation of the resource in the response. The constraints matter more than the label.
Should I use PUT or PATCH?
PUT replaces the whole resource, so a missing field is removed. PATCH applies a partial update, so a missing field is left alone. Use PATCH for a partial update.
How should I version an API?
A version in the URL path is the most common and the easiest to route and document. A version in a header is more correct in theory but harder to test and debug.
What status code should I return for a validation error?
400 Bad Request for a malformed request, and 422 Unprocessable Entity for a request that is well-formed but fails validation. Include the field errors in the body.
How do I handle pagination?
Offset pagination is simple but drifts when items are added. Cursor pagination is stable and scales better. Use a cursor for a large or frequently changing collection.
Should an API return 200 with an error in the body?
No. The status code is the machine-readable outcome, and a client, a proxy, and a monitoring system all read it. Return the correct status code and put the detail in the body.