The ideas behind REST
The web is the largest distributed system people have built. It reached that size without being redesigned, because a small set of architectural constraints was followed from the start. REST is the name for that set.
REST is an architectural style, not a protocol
The first thing to correct: REST is not another name for 'JSON over HTTP'.
A dissertation, in the year 2000
Roy Fielding was one of the authors of the HTTP/1.1 specification. He looked back at the web he had helped build and asked one question: why can it grow from a few machines to a global system without falling apart? He wrote his answer as an architectural style in chapter 5 of his doctoral dissertation and named it REpresentational State Transfer, shortened to REST.
The order matters. REST did not come first, with the web built to follow it. The web came first. REST is Fielding's description of why the web works.
REST is not a test you pass or fail. It is a set of constraints, and a system can follow all of them, some of them, or none. The more of them it follows, the more it can rely on infrastructure the web already provides: caches, proxies, and clients that were not written for that one API. Most APIs called REST follow some of the constraints, not all — this chapter is about which ones, and why they matter.
A protocol fixes the exact format of a message. HTTP is a protocol. Get one byte wrong and the other side cannot read it. A protocol has version numbers and a written specification.
A style is a set of design principles. Nothing enforces it. REST has no version number, no official certification, and no error response that says "not REST".
RESTful means "follows the REST style". Calling an API RESTful describes a degree, not a yes or no. §04 gives you a scale to measure it with.
So these sentences are wrong
"REST means JSON over HTTP." "If it returns JSON, it is a REST API." Both are wrong. Fielding's dissertation does not mention JSON — JSON was not in common use in 2000. REST is about architecture: how resources are named, how state moves between client and server, and how responses can be cached. Which format carries the data is a separate decision. The next section shows one resource in three formats.
For scale: Postman's 2025 State of the API report found that 93% of teams work with REST APIs. It is the default style for public APIs. Even so, by Fielding's own standard most of them do not qualify. §04 shows where the line sits.
Three ideas: resource, URI, representation
A thing, its identifier, and a copy of it in one format. Everything else in REST is built on these three.
Anything worth naming: user 42, this article, today's weather in Hangzhou. Resources are nouns. A resource is the thing itself — an abstract concept, not a file.
The identifier of a resource. /users/42 identifies the user, not a JSON file stored somewhere. Anything you can name can have a URI.
The resource captured at one moment, in one format. JSON is one representation; HTML is another. There can be many representations, but only one resource.
fetch code asks for. It is a copy of the resource as it is right now, not the resource itself.Because resources are the nouns, the HTTP method carries the verb. POST /createUser puts the verb back into the URI, and REST avoids that. The reason is the uniform interface, not taste: if every API invents its own action names, a cache or a proxy cannot tell what a request does, and no general-purpose tool can be written for it. POST /users says the same thing using the one vocabulary every HTTP component already understands. Chapter 04 turns this into concrete naming rules.
Where the name REST comes from
REpresentational State Transfer. The client never holds the resource itself; it holds a representation of it. Each time the client follows a link and makes a request, a new representation is transferred and the application moves to a new state. Browsing a website is exactly this: every click transfers a new representation and changes the state you are in.
The six constraints
Fielding derives REST by adding one constraint at a time. Five are required and one is optional. Click a card to turn it over.
The uniform interface has four parts
The uniform interface is the constraint that separates REST from other styles, and Fielding splits it into four. ① Identification of resources: every resource has a URI. ② Manipulation of resources through representations: the client sends back a modified representation, and the server decides how to apply it. ③ Self-descriptive messages: a message carries what is needed to understand it — the method, the status code, the media type — with no agreement negotiated outside the message. ④ HATEOAS, hypermedia as the engine of application state, which §05 covers on its own.
Of the six, stateless is the one people find hardest to accept. Having the server remember the user seems convenient. But it is the reason a website can be scaled by adding machines. The comparison below runs the same session against two servers.
Stateless does not mean the server stores nothing
A common misreading: "does stateless mean the server cannot have a database?" No. Resource data — articles, users, orders — is stored as usual. What the server does not keep between requests is session state: who you are logged in as, which page you were reading. That part travels with the client and is sent again with every request.
The Richardson maturity model: how close to REST are you?
A scale proposed by Leonard Richardson and made widely known by Martin Fowler. It is not an official standard, but it is the scale the industry uses.
Reading an order? Still POST /pizzaService, with action set to checkOrder. Cancelling? Another action value. One URL, one method, always 200, and errors hidden inside the body. HTTP is reduced to a tunnel for moving data. Fowler calls this the swamp of POX (plain old XML).
Back to that 93%
Most of those self-described REST APIs stop at L2. So "REST" as the industry uses the word usually means "L2 plus JSON". That is not a failure. L2 already gets you most of what HTTP offers: caching, idempotent methods, and tools that work with any API. It is still worth knowing that the scale has one more step.
HATEOAS: the idea, and what actually gets built
The requirement for L3, the part Fielding considers essential, and the reason it is rarely implemented.
HATEOAS stands for Hypermedia As The Engine Of Application State. The idea is one you already use every day: you browse the web. You do not memorize URLs; the page gives you links and you click them. HATEOAS applies the same idea to programs. The response includes links, and the client follows them instead of building URLs from rules written into its own code.
In practice you have probably seen a partial version of this. GitHub's API returns a set of *_url fields:
starred_url also shows a URI Template (RFC 6570): {/owner}{/repo} are placeholders the client fills in. The first task in §06 asks you to count these fields.Fielding's 2008 blog post
By 2008, very few APIs calling themselves REST were driven by hypermedia. Fielding published a post titled REST APIs must be hypertext-driven, arguing that if the engine of application state is not hypermedia, the API is not REST — follow the constraint or pick a different name. By that standard, most APIs described as REST today would need a different name.
Measurements agree with him. A 2019 study of the most-used public web APIs (RESTful or RESTless — Current State of Today's Top Web APIs, arXiv:1902.10514) found that only a small share of them put links to related resources in their responses. HATEOAS is the least implemented of the constraints. Four reasons come up again and again. First, the client and the API are usually written by the same team, so discovering endpoints at runtime has little value. Second, links make responses larger and add extra round trips. Third, there is no single format — HAL, JSON:API, and Siren all do it differently. Fourth, support in frameworks and client libraries has stayed thin.
An honest summary
What the industry calls REST is usually L2 plus JSON. This course follows that reality: chapters 04 and 05 are all L2 practice. But you now know what the full idea asks for. The next time HATEOAS comes up, you can explain what it requires, how little of it is built, and why.
Practice
Three tasks: find hypermedia links in a real API, then practice judging maturity level and modeling resources.
Chapter quiz
Eight questions. 'What is REST' is a common interview question. After this chapter you can answer it with the detail most people miss.
Which sentence describes what REST is most accurately?
You send GET /users/42 and receive some JSON. Strictly speaking, what is that JSON?
Which of these are REST constraints? (select all that apply)
What does the stateless constraint actually require?
Which of the six constraints is the only optional one?
An API gives each kind of resource its own URL, uses GET, POST and DELETE for what they mean, and returns 201 and 404 correctly. Its responses contain no links. Which maturity level is it at?
What does HATEOAS describe?
Same URI, but you want the XML representation. Which request header do you set? (write the header name only)
- REST is an architectural style — not a protocol and not a data format. It is a set of constraints, and the more of them your system follows, the more of the web's existing infrastructure it can reuse.
- Three ideas: the resource is the thing, the URI is its identifier, and the representation is a copy of it in one format at one moment. JSON is the most common representation, not a requirement — change the
Acceptheader and you get another one. - Stateless means each request carries everything needed to understand it, and session state stays with the client. It does not mean the server stores no data. This is what makes it possible to scale by adding machines.
- The maturity model: L0 one endpoint → L1 separate resources → L2 methods and status codes → L3 hypermedia. What the industry calls REST is usually L2 plus JSON.
- HATEOAS asks the server to put the available next steps into the response as links. Few APIs do it, and Fielding considers those APIs not REST. GitHub's
*_urlfields are a partial example.