Read on Twitter
Years ago now I did a mountain of research on web API design and architecture.
The main thing I learned: almost nobody has the first fucking clue what "REST" is. I'd like to clear up some common misconceptions. (Thread)
The main thing I learned: almost nobody has the first fucking clue what "REST" is. I'd like to clear up some common misconceptions. (Thread)
1. REST is not a specification.
It's a term coined to describe the architecture that allowed the WWW to become popular. It is *descriptive* not prescriptive.
It's a term coined to describe the architecture that allowed the WWW to become popular. It is *descriptive* not prescriptive.
2. The primary thing that makes an API "RESTful" is the presence of links.
One of the things that allows the web to be so widespread and popular is that you only really need to know one URL for a whole website. Internal navigation allows you to access everything underneath.
One of the things that allows the web to be so widespread and popular is that you only really need to know one URL for a whole website. Internal navigation allows you to access everything underneath.
Which is to say: if your API doesn't include references to other API endpoints in its payload -- if you can't navigate the entirety of your API via those links from the root -- then it's not fully RESTful.
3. The primary "unit" of a RESTful API is a "resource", but the primary defining feature of a resource is that it lives at a fixed location (a URL).
People love to project a lot of meaning onto this, but that's really as far as it goes.
People love to project a lot of meaning onto this, but that's really as far as it goes.
Put another way: there is no requirement that you "normalize" your APIs. You can have one end-point that shows a list of items and a SECOND end-point that has a list of those same items with some sub-items pulled in.
Having both in the same API doesn't make it not RESTful.
Having both in the same API doesn't make it not RESTful.
From the standpoint of "REST", those are just different resources. REST doesn't care one bit if they're represented by the same database table underneath.
4. "Resources" have "Representations" -- you are not required to have multiple representations for every resource, BUT YOU CAN. This can take a bunch of forms. The simplest is different serializations: i.e. JSON vs. XML
But you can *ALSO* use this mechanism to implement the "list view" and "list view with extra details" from a few tweets back. Those could be thought of as different representations.
In HTTP, this feature is exposed using the "Accepts" family of headers.
In HTTP, this feature is exposed using the "Accepts" family of headers.
5. REST describes all interactions as stateless. Because most folks are building APIs over HTTP, this happens by default, but it's worth being aware of.
6. The main "promise" of REST is that someone could build a generic API browser and all it would need to know is the root API endpoint and it could successfully navigate the rest of the API.
This works well on the web because our browsers are aided by a tremendously powerful CPU: our brains. Browsers typically work by showing things to a human, who then decides what to do next. Web APIs don't work like that, except when we're building them initially.
So, in an API, the primary benefit of "HATEOAS" (the fancy, official term for those end-point-to-end-point links) is for discoverability while you're building your integration and the OCCASIONAL programmatic navigation (as, sometimes, with pagination).
The corollary here is that "RESTful" is not inherently good or bad. It's just one architecture choice.
"Because it is (or isn't) RESTFUL" isn't a good argument for doing (or not doing) something in your API design.
"Because it is (or isn't) RESTFUL" isn't a good argument for doing (or not doing) something in your API design.
7. Final point: if you ask 10 devs what a "RESTful" API is, you will get 16 different answers, so "adhering" to REST is also not particularly valuable as a way to communicate about the architecture of your API. People are still going to have to read your docs.
Postscript: I still prefer REST to GraphQL, but that's a whole different thread.