A collection of points to remember when designing REST-APIs.
It's generally recommended to use OpenAPI. Chose between Design First or Code First.
- 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 /userswill 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
- Usually plural names are preferred as it makes clearer that
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 (POSTfor large and complex queries that cannot be included in the URL)DELETE-> DeletePUT-> Create with user defined IDsPUT-> Update as a full replacementPOST-> Create for unknown IDs (sent to a collection ressource, responds with to201andLocationheader)POST-> Update for partial updates (responds with200)
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.
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 |
❌ | ❌ |
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.
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.
Write a styleguide for the developers, that ideally includes a list of useful patterns to apply while designing.
Examples: