Notes on REST-API design

A collection of points to remember when designing REST-APIs.

OpenAPI

It's generally recommended to use OpenAPI. Chose between Design First or Code First.

Methods and URLs

Think in terms of resources (Uniform Resource Locator)
Use nouns in URLs and describe the action via HTTP methods
Chose between (and stick to) singular or plural names
- Usually plural names are preferred as it makes clearer that GET /users will return a collection
- But sometimes the plural and singular form are indistinguishable or the word doesn't have a plural form. This could cause some confusion

CRUD

The CRUD operations do not map one to one to HTTP verbs. The following usages are actually derived from HTTP standards and mandates (e.g. based on idempotency):

GET -> Read (POST for large and complex queries that cannot be included in the URL)
DELETE -> Delete
PUT -> Create with user defined IDs
PUT -> Update as a full replacement
POST -> Create for unknown IDs (sent to a collection ressource, responds with to 201 and Location header)
POST -> Update for partial updates (responds with 200)

Examples:

# list all users
GET    /users    # 200 OK

# create a new user under the given id
PUT    /users/1  # 201 Created

# create a new user
POST   /users    # 201 Created, Location: https://api.example.com/users/1

# get a single user
GET    /users/1  # 200 OK

# fully update a single user
PUT    /users/1  # 200 OK, 204 No Content

# partially update a single user
POST   /users/1  # 200 OK, 204 No Content

# delete
DELETE /users/1  # 200 OK, 202 Accepted, 204 No Content

Payloads omitted for brevity.

Idempotency and Safety

A request method is considered idempotent if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. And it's worthwhile to mention that idempotency is about the effect produced on the state of the resource on the server and not about the response status code received by the client.

An HTTP method is safe if it doesn't alter the state of the server. In other words, a method is safe if it leads to a read-only operation.

stackoverflow.com/a/45019073 – MDN glossary: Idempotent – MDN glossary: Safe

method	idempotent	safe
`GET`	✔️	✔️
`HEAD`	✔️	✔️
`OPTIONS`	✔️	✔️
`PUT`	✔️	❌
`DELETE`	✔️	❌
`POST`	❌	❌
`PATCH`	❌	❌

Content

Resources should include all relevant information and thus avoid making more requests. When returning a collection of items, some information may be omitted. In that case the entities should have a URL to the full resource.

Responses

Only use objects as the top level element, as it's the only way to add information later on without breaking everything.

Define common / reserved property names and naming conventions in data objects, e.g. name date/time properties with _at suffix or Reserved Property Names for Paging.

Alot of the styleguides below use a generic wrapper object, which is difficult to do with OpenAPI. Consider creating your own OpenAPI dialect and generator with vendor extensions.

Styleguides

Write a styleguide for the developers, that ideally includes a list of useful patterns to apply while designing.