Card 03/ 11
Collections and Items: /orders and /orders/{id}
A plural noun names the set, an identifier after it names one member, and the method says what to do.
Resource-oriented paths come in two shapes: a collection, named by a plural noun such as /orders, and an item in it, named by the collection plus an identifier, such as /orders/42. The path only names things; the HTTP method says what to do with them. Two paths and five methods cover the operations most resources need.
| Method and path | Operation | Typical success |
|---|---|---|
| GET /orders | List the orders | 200, with a list |
| POST /orders | Create an order; the server chooses its id | 201, with Location /orders/43 |
| GET /orders/42 | Read one order | 200, with the order |
| PATCH /orders/42 | Change part of the order | 200, with the updated order |
| PUT /orders/42 | Replace the whole order | 200, or 201 if it did not exist |
| DELETE /orders/42 | Remove the order | 204 |
These operations are often called CRUD, for create, read, update and delete, the four basic things done to stored data.
Plural nouns, always. /orders and /orders/42 read as "the orders" and "order 42 of the orders". Mixing /order/42 with /orders makes clients guess which form each resource uses.
Stable identifiers. The id in the path should never change for the life of the resource, so a stored URL keeps working. Use an opaque value, such as a number or a random string, rather than something that can change, such as a customer's email. Random ids also stop a caller learning how many orders exist by counting.
Lowercase, with hyphens. Paths are case sensitive after the host, so pick one form: /order-items, not /orderItems in one place and /order_items in another.
No file extensions or trailing slashes. /orders/42.json puts the format in the path, where the Accept header belongs. /orders/ and /orders should not be two different resources; choose one and redirect the other.
So design each resource as one plural collection and its items, and let the method carry the verb.
← → move through sections and cards