System Design Concepts · API Design
Thinking in resources: what REST actually is
REST is constraints, not JSON over HTTP: address resources, let methods decide the action, send hypermedia links to what's next and more.
REST is a set of constraints
- REST starts as a name and nothing more. No constraints are in place yet, so the name has no meaning.
- The first two constraints are in place: client-server and stateless. REST starts to mean something.
- The next two constraints are in place: cacheable and uniform interface. Each added constraint gives the name REST more meaning.
- The fifth branch, the layered system constraint, joins the other four. All five constraints are met, so the REST label is fully drawn.
- A WebSocket design keeps session state on the server. So the branch for REST's stateless constraint is marked as broken.
- The stateless branch detaches from the tree of constraints and falls away. Statelessness is the one constraint being dropped.
- Four constraints are still in place, but stateless is gone. So the design is no longer REST.
Six endpoints become four addresses
- The API has six endpoints, all of them POST, and each is named after an action. There are no resources yet, so nothing has an address of its own.
- The address /users/123 appears. The three user endpoints become methods on that one address: GET, PUT and DELETE. So six endpoints become three, and one address holds them.
- The collection address /users, plural because it holds every user, appears above /users/123. Finding a user by email is a filter on that collection, GET /users?email=, not an endpoint of its own, so three endpoints become two.
- Orders belong to a user, so /users/123/orders is nested one level under /users/123 and takes GET and POST. No named endpoint is left.
- A path keeps nesting: /users/123/orders/456/items/7. That deep path is removed. An order has its own id, so /orders/456 is an address on its own. Nest one level to show ownership, and stop there.
- The addresses now match the domain: users have orders. Four addresses and six methods have replaced the six named actions.
Links tell the client what it may do next
- Two clients load /orders/123, status pending. Client A shows Cancel and Pay from its own built-in URL map, but Client B shows nothing, because the response has no links yet.
- The server now adds a _links block to the response, listing cancel and pay. Client B draws Cancel and Pay from those links. Client A keeps drawing from the map it shipped with.
- The order is now paid. The response says paid, and its links say refund. So Client B removes Cancel and Pay and shows Refund. Client A still shows Cancel and Pay.
- Client A sends Cancel from its own URL map and gets 409, because the order is paid. Client B sends Refund from the link in the server's response and gets 200. Client B never built a URL, and only offered actions the server had offered first.
- The server stops sending links, so both clients get the same response with no _links block, and client B has no actions to show. Most APIs stop here, at level 2: resources and methods, URLs in the docs, no links in the body.
- Client A now generates its URL map from the OpenAPI spec instead of shipping one, so a moved URL fails the build, not the user. Most production APIs are HTTP APIs at level 2 by choice, and saying so is better than claiming REST.
© LearnThatStack - diagrams may not be republished without permission.
Ask an engineer what REST is and you usually get a tool list: JSON, HTTP verbs, a URL scheme. That list cannot tell a RESTful API apart from any other API that sends JSON.
REST is a set of constraints. First is client-server: the client owns the interface, the server owns the data. and Stateless means every request carries everything needed to answer it. So any instance behind the load balancer can take the next request.
Next is Cacheable. It means a response indicates whether a client or a proxy may keep a copy, so repeated reads never reach your server. Then, Uniform interface - it refers to the shape and structure: resources at addresses, standard methods, and links in the response.
Layered system is the fifth constraint. A client cannot tell whether it is talking to the origin server, a cache, or a load balancer in front of that server. This is REST - all these five constraints.
If a design broke one of the constraint say stateless. For example - a WebSocket connection holds session state on the server between messages, to know which client is connected, and what that client last saw. A request on that connection no longer carries everything needed to answer it, so its no longer stateless.
So you gave it up the stateless constraint to keep the connection open. The other four are still good, and the design can be the right one. WebSockets are the right call for a live chat feed.
Four constraint branches are still in place, and the API still sends JSON over HTTP. This is a WebSocket design, it is not REST.
What does 'the uniform interface' mean. The six POST endpoints on the left are each named after an action, so that API ignores the uniform interface. Every feature got its own name, which felt natural but it has its cost.
Instead, name the thing and you got one address, /users/123. The three user endpoints become methods on that address: GET reads the user, PUT replaces the user, DELETE removes the user. Six endpoints will become three, all on that one address. The method carries the action, and the URL is the name of the resource.
The collection for the item is the same noun, plural - /users. Finding a user by email is not an action worth a name. That search is a filter on the collection, GET /users?email=. The collection keeps one address, and you can add as many filters later.
Orders belong to a user, so /users/123/orders sits one level under /users/123 and allows GET and POST actions. The path defines who owns what. The left column, the list of actions, is empty now. Every action has an address and a method.
Be careful of nesting. The path /users/123/orders/456/items/7 repeats ids that already identify things on their own. Nesting is a habit that does not know where to stop. An order has its own id, so /orders/456 stands alone and items sit under that path. So usually, nest one level to show ownership, and stop there.
The address tree should read like the domain: users have orders. And a client should be able to guess addresses that match your entities. A verb in a path means you are calling a function over HTTP, not addressing a resource.
One constraint is still missing, and this is not commonly implemented in practice: the uniform interface also asks for links in the response. Two clients load the same order, status pending. Client A has a map of URLs and and got the Cancel and Pay buttons from that map. Client B got nothing, because nothing in the response said what Client B may do.
The server adds a _links block with cancel and pay, then sends the value to client B. Client B reads the links and got two things it can do next, Cancel and Pay. Sending the links with the value is HATEOAS, hypermedia as the engine of application state. The order's state decides which links appear, and those links decide what the client offers.
The order is paid, so the response says paid and the links say refund. The new value reaches Client B. Client B stops getting Cancel and Pay and got Refund instead, with no code change. Client A still got Cancel and Pay, because its map from state to buttons does not know the order is now paid.
Client A sends Cancel from its own map of URLs and gets a 409. Client B sends Refund from a link the server sent and gets a 200. B never built a URL and never offered an action the server had not offered first, so the server can move URLs and rules without breaking B.
Client A keeps working without the links, but client B has nothing left to display. So why does almost nobody ship hypermedia? Most APIs stop at level 2 of the Richardson model: resources and methods, URLs in the docs and the SDK, no links in the body. Level 3 adds the links.
A generated SDK fails the build when a URL moves. The build failure is the protection level 3 would have given at runtime. Most teams make that trade on purpose: an HTTP API at level 2. They instead use OpenAPI spec to publish their URL map.
REST is a set of constraints, and dropping one means you cannot call your API REST. In practice the uniform interface means addresses for things and methods for actions. Addresses nest one level deep to show ownership. Hypermedia is the links in response for what the client may do next, but many APIs skip this constraint.
In interviews · 4 questions
Related Questions
- 01
- 02
- 03
- 04