REST API design: Resources, methods and status codes

In short: Basic rules for designing a web interface so that it is predictable: things as resources, HTTP methods for actions, status codes for results.

In more detail: REST is an architectural style for web interfaces. Instead of custom verbs such as /getUser or /deleteOrder, you use the existing capabilities of HTTP. Whoever knows the rules can understand foreign interfaces quickly and build their own so that they need little explanation.

In Depth

Resources in URLs

A URL names a thing (noun, usually plural), not an action:

GET    /customers            list of customers
GET    /customers/42         one customer
POST   /customers            create a new customer
PUT    /customers/42         replace customer
PATCH  /customers/42         change customer partially
DELETE /customers/42         delete customer
GET    /customers/42/orders  subordinate resource

Methods and their properties

GET reads and changes nothing (safe). GET, PUT and DELETE are idempotent: executing them several times results in the same state as once. POST is not; a second call can create two customers. That is why keys for retry safety are usual for critical POST requests.

Status codes

• 200 OK, 201 Created (with Location header), 204 No Content.
• 400 Bad Request (invalid input), 401 Unauthorized (not signed in), 403 Forbidden (no permission), 404 Not Found, 409 Conflict, 422 Unprocessable Content, 429 Too Many Requests.
• 500 and above: errors on the server. Error responses should have a uniform format with an understandable message, for example following RFC 9457 (problem details).

Further notes

For lists, pagination, filtering and sorting belong as query parameters (?page=2&sort=name). Data is usually delivered as JSON with consistent names and ISO 8601 dates. Describe the interface in a specification such as OpenAPI. Pure REST has limits, for example with deeply nested queries, for which GraphQL or RPC styles may be more suitable.

See also: APIs, Pagination