Card 01/ 11
REST: An Architectural Style, Not a Protocol
REST is a set of constraints on a system, and an API is RESTful as far as it keeps them.
REST, short for representational state transfer, is a set of constraints Roy Fielding described in 2000 for building systems like the web. It is not a protocol, a format or a library: an API is RESTful to the degree it keeps the constraints, and each constraint buys the system a property, such as scaling out or letting caches answer.
| Constraint | Requires | Buys |
|---|---|---|
| Client and server | The interface is the only thing the two sides share | Each side can change on its own |
| Stateless | Each request carries everything needed to answer it | Any server can answer any request, so servers can be added freely |
| Cacheable | Responses say whether they may be reused | Caches can answer, which cuts load and latency |
| Uniform interface | Every resource is named by a URI and used through the same methods | Clients learn one way to talk to everything |
| Layered system | A client cannot tell whether it talks to the server or something in between | Proxies, gateways and CDNs can sit in the path |
| Code on demand, optional | The server may send code for the client to run | Clients can be extended after they ship |
Stateless does not mean the server stores nothing. The orders in the database are the application's state, and they stay. Stateless means the server keeps no memory of the conversation between requests: no "current page" held for a client, no step of a wizard remembered in server memory. Each request says who is calling and what it wants, usually with a token in a header.
Representation is the word in the name. A client never touches the order itself; it receives a representation of it, such as a JSON document, and sends representations back to change it. The same order could be represented as JSON, XML or HTML.
The uniform interface does the most work. It is why a client that knows GET /orders/42 can guess GET /customers/7, and why a cache that has never seen an API knows it may store a GET. It has a fourth part, hypermedia, where responses link to what the client may do next; most APIs skip it.
Why it matters for design. Many APIs call themselves RESTful while keeping only some constraints, and that is often fine. What matters is knowing which ones an API keeps and what it gives up by dropping the rest: an API that stores session state on one server cannot add a second without moving that state.
So treat REST as a checklist of properties to buy, not a badge to claim.
← → move through sections and cards