REST & Resource Modeling

Every component this course has covered so far, whether server, cache, queue or database, eventually needs a contract that lets clients and other services talk to it. That contract is the API, and REST is still the most common shape it takes. REST is not a technology or a library. It is a way of organizing an API so that it is predictable: once you have learned how one REST API works, you can guess how most others do.

In a library, every book has a unique shelf mark that says exactly where it is. And there is a small, fixed set of things you can do with any book: look at it, borrow it, return it, ask for it to be reserved. You do not need a different procedure for each book, because the address says which book and the action says what to do.

• -The shelf mark is the URL: a unique address for one thing, such as /books/42.
• -The book (or any other thing the API is about) is a resource, named with a noun.
• -The small, fixed set of actions is the HTTP methods: GET, POST, PUT, PATCH and DELETE.
• -The librarian's answer is the response: a status code that says how it went, and usually the thing itself.

The central rule of REST is that URLs name things, not actions, and the HTTP method is the action. So the URL is /users/42, never /getUser or /deleteUser. A collection is a plural noun and one member of it is the id after it:

• -/users is the collection of all users: GET lists them, POST adds a new one.
• -/users/42 is one user: GET reads it, PUT replaces it, PATCH changes part of it, DELETE removes it.
• -/users/42/orders are the orders belonging to user 42, a nested resource that shows the relationship.

Keep nesting shallow, two levels at most. Once you have an order's id, /orders/9001 is clearer than /users/42/orders/9001. Use the query string to filter or sort rather than to name things: /orders?status=shipped&sort=-created_at.

• -GET reads a resource. It must not change anything (it is safe), and repeating it does no harm.
• -POST creates a new resource, or triggers a process. Repeating it creates another one, so it is not idempotent.
• -PUT replaces a resource with the one you send. Repeating it leaves the same result.
• -PATCH changes only the fields you send.
• -DELETE removes a resource. Repeating it leaves the same result: the thing is gone.

Idempotent means that doing the same request twice has the same effect as doing it once, and it matters because networks fail and clients retry. If a client sends DELETE /orders/9001 and the connection drops before the answer arrives, retrying is safe: the order is gone either way (the second reply may be 404, but the state is the same). If it retries POST /orders, it may create two orders. This is the reason the idempotency chapter later in the course exists.

Here is a complete exchange that creates an order for user 42:

Choose the status code to tell the client what happened. The common ones, by who is at fault. Success: 200 OK, 201 Created and 204 No Content (nothing to return). The client's fault: 400 Bad Request (the request itself is wrong), 401 Unauthorized (not logged in), 403 Forbidden (logged in but not allowed), 404 Not Found, 409 Conflict (it clashes with the current state) and 429 Too Many Requests. The server's fault: 500.

A REST request carries everything the server needs, including who is asking, usually in a token, so that any server can answer it. That is the stateless idea from the three-tier module, and it is why REST APIs scale out so easily behind a load balancer.

Some operations do not fit create, read, update and delete: cancel an order, publish a post, transfer money. Two good options exist. Treat the action as a change of state: PATCH /orders/9001 with {"status": "canceled"}. Or give the action its own noun and create it: POST /orders/9001/cancellation, or POST /transfers. Avoid the shortcut of inventing verbs in URLs such as /cancelOrder, because it throws away the predictability that makes REST useful.

The Wiki card below sets REST in the wider context of API design: