REST (Representational State Transfer) is an architectural style for distributed systems, described in Roy Fielding’s 2000 doctoral dissertation, which has been cited approximately 30,000 times and understood approximately 47 times.
REST is the most widely claimed and least widely practiced architectural style in software. Every API written since 2005 calls itself “RESTful.” Almost none of them are. REST, as Fielding described it, has six constraints. The average “RESTful” API implements one and a half of them, violates three, has never heard of one, and uses the word “RESTful” in its documentation because it sounds better than “HTTP API with JSON.”
“I am getting frustrated by the number of people calling any HTTP-based interface a REST API.”
— Roy Fielding, 2008 (and every year since)
The Dissertation Nobody Read
Fielding’s dissertation — “Architectural Styles and the Design of Network-Based Software Architectures” — is Chapter 5 of a larger work about architectural styles. It describes REST as a set of constraints for building scalable, evolvable distributed systems:
- Client-Server — separate the user interface from the data storage. Everyone does this. Point: the industry.
- Stateless — each request contains all information needed to process it. Most APIs do this. Point: the industry.
- Cacheable — responses must define themselves as cacheable or not. Some APIs do this. Half point.
- Uniform Interface — resources identified by URIs, manipulated through representations, self-descriptive messages, and HATEOAS. Almost nobody does this. See below.
- Layered System — the client doesn’t know whether it’s connected to the end server or an intermediary. Proxies and load balancers handle this. Point: infrastructure.
- Code-on-Demand (optional) — servers can extend client functionality by transferring executable code. JavaScript. This was prescient in 2000.
The industry implemented constraints 1, 2, and 5 (which are just “how HTTP works”), partially implemented 3, completely ignored 4, and forgot 6 existed. Then the industry called the result “REST.”
HATEOAS
HATEOAS (Hypermedia As The Engine Of Application State) is REST’s most important constraint and the one that 99.7% of “RESTful” APIs do not implement.
HATEOAS means: the server’s response tells the client what it can do next, through hyperlinks. The client doesn’t need to know the API’s URL structure in advance. The client follows links, like a human browsing the web.
{
"id": 42,
"name": "Widget",
"price": 9.99,
"_links": {
"self": { "href": "/products/42" },
"purchase": { "href": "/orders", "method": "POST" },
"reviews": { "href": "/products/42/reviews" }
}
}
The client knows it can purchase the widget because the response told it so. If the widget is out of stock, the purchase link disappears. The client doesn’t hard-code URLs. The client discovers them.
This is REST. This is what Fielding meant. This is what nobody does.
What everyone does instead: hard-code /api/v2/products/42 in the client, document the URL structure in Swagger, break the client every time the URL changes, and call it RESTful because the verbs are HTTP verbs.
Fielding has been pointing this out since 2008. The industry has been politely ignoring him since 2008.
What “RESTful” Actually Means
In practice, “RESTful API” means:
- Uses HTTP
- Returns JSON (not XML, because it’s not 2007)
- Uses GET, POST, PUT, DELETE (sometimes PATCH, always debated)
- Has URLs that look like
/resources/{id} - Returns 200 for success (and also for errors, sometimes)
- Has documentation (usually Swagger/OpenAPI)
This is not REST. This is “HTTP API with conventions.” It is a perfectly reasonable way to build APIs. It is also not what Fielding described, and calling it REST is like calling a shed a cathedral because both have a door.
The industry’s “REST” is a useful convention. Fielding’s REST is an architectural style. The convention won because it was easy. The style lost because HATEOAS is hard and nobody’s client library supports link traversal and the front-end developer just wants to know the URL to call.
The Holy Wars
REST generates theological disputes that would make medieval scholastics envious:
PUT vs. PATCH: PUT replaces the entire resource. PATCH updates part of it. The debate about when to use which has consumed more engineering hours than the actual implementations of either.
Verbs in URLs: /getUser/42 is heresy. /users/42 with GET is orthodoxy. The heresy works. The orthodoxy works. The debate continues.
Status codes: Should a validation error be 400 or 422? Should “not found” be 404 or a 200 with an error body? Should authentication failure be 401 or 403? Each question has a correct answer. Each correct answer has a popular alternative. Both are deployed in production.
Versioning: URL path (/v2/), header (Accept: application/vnd.api.v2+json), or query parameter (?version=2)? The correct answer is “it depends.” The popular answer is /v2/ because it’s visible. Fielding would say you don’t need versioning if you implement HATEOAS. Fielding is correct. Nobody implements HATEOAS.
Plural vs. singular: /user/42 or /users/42? This debate has no theological resolution. It has only convention. The convention is plural. The reason is vibes.
Measured Characteristics
Year described: 2000
Fielding dissertation citations: ~30,000
People who read Chapter 5: ~500
People who understood Chapter 5: ~47
APIs calling themselves RESTful: millions
APIs that are actually RESTful: dozens
APIs implementing HATEOAS: dozens
PUT vs. PATCH debates (active): thousands
Status code debates (active): thousands
Time spent on plural vs. singular: irrecoverable
Roy Fielding's frustration level: increasing
Average "RESTful" constraints implemented: 1.5 of 6
JSON responses: 99%
XML responses: 1% (legacy, grieving)
