books/The-API-Book
1
0
Fork 0
mirror of https://github.com/twirl/The-API-Book.git synced 2025-05-31 22:09:37 +02:00
Code Issues Releases Activity

REST

Browse Source
This commit is contained in:
Sergey Konstantinov 2023-06-01 00:27:54 +03:00
parent 89bb1aa895
commit 5ac95220c0
1 changed files with 22 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
src/en/clean-copy/05-[Work in Progress] Section IV. The HTTP API & REST/02.md
View File

@ -1,33 +1,43 @@
### [The REST Myth][http-api-rest-myth]
Before we proceed to discuss HTTP API design patterns, we feel obliged to clarify one more important terminological issue. Often, an API matching the description we gave in the previous chapter, is called “REST API” or “RESTful API.” In this Section, we don't use any of these terms as it makes no practical sense.
Before we proceed to discuss HTTP API design patterns, we feel obliged to clarify one more important terminological issue. Often, an API matching the description we gave in the previous chapter is called a “REST API” or a “RESTful API.” In this Section, we don't use any of these terms as it makes no practical sense.
What is “REST”? In 2000, one of the authors of the HTTP and URI specifications, Roy Fielding, published his doctoral dissertation titled “Architectural Styles and the Design of Network-based Software Architectures,” the fifth chapter of which was named “[Representational State Transfer (REST)](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).”
What is “REST”? In 2000, Roy Fielding, one of the authors of the HTTP and URI specifications, published his doctoral dissertation titled “Architectural Styles and the Design of Network-based Software Architectures,” the fifth chapter of which was named “[Representational State Transfer (REST)](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).”
As everyone might assure by reading this chapter, it features a very much abstract review of a distributed client-server architecture bound to neither HTTP nor URL. Furthermore, it does not discuss any API design recommendations. In this chapter, Fielding methodically *enumerates restrictions* that any software engineer meets when developing distributed client-server software. Here they are:
As anyone can attest by reading this chapter, it features a very much abstract review of a distributed client-server architecture that is not bound to either HTTP or URL. Furthermore, it does not discuss any API design recommendations. In this chapter, Fielding methodically *enumerates restrictions* that any software engineer encounters when developing distributed client-server software. Here they are:
* The client and the server do not know how each of them is implemented
* Sessions are stored on the client (the “stateless” constrain)
* Sessions are stored on the client (the “stateless” constraint)
* Data must be marked as cacheable or non-cacheable
* Interaction interfaces between system components must be uniform
* Network-based systems are layered, i.e., every server may be just a proxy to another server
* Network-based systems are layered, meaning every server may just be a proxy to another server
* The functionality of the client might be enhanced by the server providing code on demand.
That it. With this, the REST definition is over. Fielding further concretizes some implementation aspects of systems under the stated restrictions. However, all these clarifications are no less abstract. Literally: the key abstraction for the REST architectural style is “resource”; any data that can have a name may be a resource.
That's it. With this, the REST definition is over. Fielding further concretizes some implementation aspects of systems under the stated restrictions. However, all these clarifications are no less abstract. Literally, the key abstraction for the REST architectural style is “resource”; any data that can have a name may be a resource.
The key conclusion that we might draw from the Fielding-2000 definition of REST is, generally speaking, that *any networking software in the world complies with the REST constraints*. The exceptions are very rare.
Consider the following:
* It is very hard to imagine any system that does not feature *any* level of uniformity of inter-component communication as it would be impossible to develop such a system. Ultimately, as we mentioned in the previous chapter, almost all network interaction is based on the IP protocol, which *is* a uniform interface.
* If there is a uniform communication interface, it might be mimicked if needed, so the requirement of client and server implementation independence can always be met.
* If we can make an alternative server, it means we can always have a layered architecture by placing an additional proxy between the client and the server.
* It is very hard to imagine any system that does not feature *any* level of uniformity of inter-component communication as it would be impossible to develop such a system. Ultimately, as we mentioned in the previous chapter, almost all network interactions are based on the IP protocol, which *is* a uniform interface.
* If there is a uniform communication interface, it can be mimicked if needed, so the requirement of client and server implementation independence can always be met.
* If we can create an alternative server, it means we can always have a layered architecture by placing an additional proxy between the client and the server.
* As clients are computational machines, they *always* store some state and cache some data.
* Finally, the code-on-demand requirement is a cunning one (at least in von Neumann architectures) as we might always say that the data the client receives actually comprises instructions in some formal language.
* Finally, the code-on-demand requirement is a cunning one (at least in von Neumann architectures) as we can always say that the data the client receives actually comprises instructions in some formal language.
Yes, of course, the reasoning above is a sophism, a reduction to absurdity. Ironically, we might take the opposite path to absurdity by proclaiming that REST constraints are never met. For instance, the code-on-demand requirement obviously contradicts the requirement of having an independently-implemented client and server as the client must be able to interpret the instructions the server sends written in a specific language. As for the “S” rule (i.e., the “stateless” constraint), it is very hard to find a system that does not store *any* client context as it's close to impossible to make anything *useful* for the client in this case. (And, by the way, Fielding explicitly requires that: “communication … cannot take advantage of any stored context on the server.”)
Finally, in 2008, Fielding himself increased the entropy in the understanding of the concept by issuing 2008 a [clarification](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) explaining what he actually meant. In this article, beyond other things, he stated that:
Finally, in 2008, Fielding himself increased the entropy in the understanding of the concept by issuing a [clarification](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) explaining what he actually meant. In this article, among other things, he stated that:
* REST API development must focus on describing media types representing resources
* The client must be agnostic of these media types
* There must not be fixed resource names and operations with resources. Clients must extract this information from the server's responses.
The concept of “Fielding-2008 REST” implies that clients, after somehow obtaining an entry point to the API, must be able to communicate with the server having no prior knowledge of the API, and definitely must not contain any specific code to work with the API. This requirement is much stricter than the ones described in the dissertation of 2000. Particularly,
The concept of “Fielding-2008 REST” implies that clients, after somehow obtaining an entry point to the API, must be able to communicate with the server having no prior knowledge of the API and definitely must not contain any specific code to work with the API. This requirement is much stricter than the ones described in the dissertation of 2000. Particularly, REST-2008 implies that there are no fixed URL templates; actual URLs to perform operations with the resource are included in the resource representation (this concept is known as [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)). The dissertation of 2000 does not contain any definitions of “hypermedia” that contradict the idea of constructing such links based on the prior knowledge of the API (such as a specification).
**NB**: leaving out the fact that Fielding rather loosely interpreted his own dissertation, let us point out that no system in the world complies with the Fielding-2008 definition of REST.
We have no idea why, out of all the overviews of abstract network-based software architecture, Fielding's concept gained such popularity. It is obvious that Fielding's theory, reflected in the minds of millions of software developers, became a genuine engineering subculture. By reducing the REST idea to the HTTP protocol and the URL standard, the chimera of a “RESTful API” was born, of which [nobody knows the definition](https://restfulapi.net/).
Do we want to say that REST is a meaningful concept? Definitely not. We only aimed to explain that it allows for quite a broad range of interpretations, which is simultaneously its main power and its main weakness.
On one hand, thanks to the multitude of interpretations, the API developers have built a perhaps vague but useful view of “proper” HTTP API architecture. On the other hand, the lack of concrete definitions has made REST API one of the most “holywar”-inspiring topics, and these holywars are usually quite meaningless as the popular REST concept has nothing to do with the REST described in Fielding's dissertation (and even more so, with the REST described in Fielding's manifesto of 2008).
The terms “REST architectural style” and its derivative “REST API” will not be used in the following chapters since it makes no practical sense as we explained above. We referred to the constraints described by Fielding many times in the previous chapters because, let us emphasize it once more, it is impossible to develop distributed client-server APIs without taking them into account. However, HTTP API (meaning JSON-over-HTTP endpoints utilizing the semantics described in the HTTP and URL standards) as we will describe it in the following chapter aligns well with the “average” understanding of “REST / RESTful API” as per numerous tutorials on the Web.