RESTful API - big lie
From the translator:
For the first time I tried to translate an article of this size and IT subjects, I’m happy to read your comments and remarks. As for the article itself: I disagree with the author at least because, in fact, it replaces REST with ... REST (!!!), but in a slightly different frame. However, despite the fact that the article presents many obvious things, it seemed to me worthy of discussion at Habré.
Why you should bury this popular technology
If over the past 10 years you have read the summary of web developers, then you will be forgiven for thinking that the RESTful API is a kind of divine talent that has come down to us from heaven. REST API is used everywhere, even marketers constantly mention it in materials intended solely for management or staff.
')
So how good is the idea of a REST API? Before we deal with this issue, let's see where the roots grow from ...
This technology became popular when it was described in detail and presented by Roy Fielding in his doctoral thesis under the name Architectural Design in 2000. Roy is known for his contributions to the development of the web, especially HTTP.
REST is a software architecture style for building distributed, scalable web services. Roy advocated the use of standard HTTP methods so as to give a specific meaning to requests.
Thus, these HTTP requests will have different meanings in REST:
There are only some types of queries above, but their entire list is: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE . If you have not even heard of some of them - it does not matter, since there are methods that are almost never supported by any client or server application.
Roy also argued that HTTP response codes would help in determining the meaning of the responses themselves. There are about 38 response codes and below you can see a list of them. Some of the names I have slightly reduced for convenience:
So, one transaction on such an API will consist of at least the following:
Many people reacted positively to this paradigm and began to use it in the development of web services using HTTP. This is what we call the RESTful API .
By the way, the transaction may be more complicated and we will discuss the reasons for this. However, we omit those complicating factors that are associated with networks and caching, as these issues are relevant to other technologies.
REST is an excellent mechanism for many things, for example, such as receiving content, and it has served us faithfully for almost 20 years. However, it is time to open your eyes and acknowledge that the concept of a RESTful API is one of the worst ideas ever developed in web development. No, I do not argue, Roy is a great guy and, of course, he had a lot of cool ideas ... However, I'm not sure that the RESTful API is on their list.
Soon we will look at another, more correct solution for building an API, but before doing so, we need to understand the 5 major problems of the RESTful API, which make it expensive, vulnerable to errors and inconvenient. Let's start!
Hardly anyone thought about why this technology is called “RESTful”, and not “RESTpure”? ( comment of the translator: pure - clear, understandable ) And because no one can decide what all the query methods, response codes, bodies, etc., are.
For example, when should we use code 200 OK ? Can we use it to confirm successful record update, or should we use 201 Created code? Apparently, you need to use the code 250 Updated , but it does not exist. And yet, can anyone explain what the code 417 Expectation failed ? Anyone other than Roy, of course.
The HTTP dictionary of methods and codes is too vague and incomplete to finally arrive at uniform definitions. There is no one, if I am not mistaken, who has found a single, general order and urged the rest to observe it. What is meant by 200 OK in one company can denote completely different information in another, which makes the technology under discussion unpredictable .
If this were the only problem, then I probably would have accepted it and continued to write the RESTful API to this day. However, our list is just being revealed ...
Even if we had solved the first problem, we would have encountered the following practical one: most client and server applications do not support all response codes and, in fact, verbs, meaning HTTP methods. For example, most browsers have limited support for PUT and DELETE.
How do we cope with this? One way is to insert a verb denoting the desired method in the form to be sent. This means that in this case the request includes:
The response code situation is no better. Different browsers (and server applications too) often understand these codes differently. For example, having received the code 307 Temporary redirect , one browser may allow the user script to view this response and cancel the action before it is executed. Another browser can simply simply forbid the script to do something. In fact, the only codes that you should not be afraid to handle are 200 OK and 500 Internal server error . In other cases, support for answers varies from “pretty good” to “just awful.” That is why we often have to supplement the body of the response with code that we actually meant .
Even if we could still agree on all of the above, and still magically fixed everything connected to the Internet, but not adapted to the REST software - we still run into another problem.
A dictionary consisting only of HTTP methods and response codes is too limited to effectively transmit and receive the various information needed by all applications. Imagine that we have created an application from which we want to send a “render complete” response to the client. Unfortunately, we cannot do this with the help of HTTP codes, because, firstly, such a code does not exist , and secondly, we cannot create it, since HTTP is not extensible . Minute of frustration. I think we will again have to insert what we mean in the body of the answer.
Also, the problem is that we have more than one dictionary, we have three of them! Response codes are numeric values (200, 201, 500) that differ from the representation of the request methods (GET, POST, PUT, etc.), and the response body is in JSON format. Performing REST transactions is like sending a letter in English to China and getting a Morse code from there. All these difficulties are a major source of confusion and mistakes. Here we go to the next global problem: debugging.
If you have once worked with the REST API, then you probably know that it is almost impossible to debug. In order to understand what happens during a transaction, we have to look at 7 places at once:
So now we have not only two very limited vocabulary, but also 7 different points where an error can be covered. The only thing that could further aggravate the situation is if the REST technology were fully tied to one protocol and it would be impossible to use any other communication channel. Actually, it is, and this is our next big problem!
RESTful API breaks into one of the fundamental laws of good communication: the content of the message must be completely independent of the transmission channel . Their mixing is the path to total confusion.
Constant interweaving of the HTTP protocol and the transmitted information completely deprives us of the possibility of transferring the RESTful API to other communication channels. Porting RESTfulAPI from HTTP to some other data transfer protocol requires completely disentangling and restructuring information from seven different points that we talked about earlier.
Fortunately, there is a good solution that allows you to avoid or minimize all the problems of the RESTful API. Meet
JSON-pure API handles most of the problems we just covered.
JSON-pure API appeared as a result of the awareness of developers of the fact that the RESTful API is not particularly friendly to browsers and developers themselves. Separating the message and transfer method makes the JSON-pure API fast, reliable, easy to use, port, and search for errors. Today, if we need, for example, to use the Twitter API, then masochists will choose the RESTful API. The rest will turn to JSON-pure API, or, as it is also called, “Web API”.
Over the past ten years, I was repeatedly asked to use RESTful instead of JSON-pure. The last time I almost had to support the RESTful API was in 2011. To my luck, the back-end team agreed to run the JSON-pure API in parallel with RESTful, simply transferring all of their methods and codes to JSON.
A few months later, all my friends who had previously used RESTful switched to JSON-pure, realizing that this is much more convenient.
Original article: mmikowski.imtqy.com/
Posted by: Michael S. Mikowski
For the first time I tried to translate an article of this size and IT subjects, I’m happy to read your comments and remarks. As for the article itself: I disagree with the author at least because, in fact, it replaces REST with ... REST (!!!), but in a slightly different frame. However, despite the fact that the article presents many obvious things, it seemed to me worthy of discussion at Habré.
Why you should bury this popular technology
RESTful api is wonderful, right?
If over the past 10 years you have read the summary of web developers, then you will be forgiven for thinking that the RESTful API is a kind of divine talent that has come down to us from heaven. REST API is used everywhere, even marketers constantly mention it in materials intended solely for management or staff.
')
So how good is the idea of a REST API? Before we deal with this issue, let's see where the roots grow from ...
Where does REST come from?
This technology became popular when it was described in detail and presented by Roy Fielding in his doctoral thesis under the name Architectural Design in 2000. Roy is known for his contributions to the development of the web, especially HTTP.
So what is a RESTful API?
REST is a software architecture style for building distributed, scalable web services. Roy advocated the use of standard HTTP methods so as to give a specific meaning to requests.
Thus, these HTTP requests will have different meanings in REST:
- GET / object / list
- POST / object / list
- PUT / object / list
There are only some types of queries above, but their entire list is: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE . If you have not even heard of some of them - it does not matter, since there are methods that are almost never supported by any client or server application.
Roy also argued that HTTP response codes would help in determining the meaning of the responses themselves. There are about 38 response codes and below you can see a list of them. Some of the names I have slightly reduced for convenience:
So, one transaction on such an API will consist of at least the following:
- Request method , for example, GET
- The query path , for example, / object / list
- Request body , for example, the form
- Answer code , for example, 200 OK
- Answer body , for example, JSON data
Many people reacted positively to this paradigm and began to use it in the development of web services using HTTP. This is what we call the RESTful API .
By the way, the transaction may be more complicated and we will discuss the reasons for this. However, we omit those complicating factors that are associated with networks and caching, as these issues are relevant to other technologies.
Actually the RESTful API is pretty awful
REST is an excellent mechanism for many things, for example, such as receiving content, and it has served us faithfully for almost 20 years. However, it is time to open your eyes and acknowledge that the concept of a RESTful API is one of the worst ideas ever developed in web development. No, I do not argue, Roy is a great guy and, of course, he had a lot of cool ideas ... However, I'm not sure that the RESTful API is on their list.
Soon we will look at another, more correct solution for building an API, but before doing so, we need to understand the 5 major problems of the RESTful API, which make it expensive, vulnerable to errors and inconvenient. Let's start!
Problem # 1: There is still no general agreement on what the RESTful API is.
Hardly anyone thought about why this technology is called “RESTful”, and not “RESTpure”? ( comment of the translator: pure - clear, understandable ) And because no one can decide what all the query methods, response codes, bodies, etc., are.
For example, when should we use code 200 OK ? Can we use it to confirm successful record update, or should we use 201 Created code? Apparently, you need to use the code 250 Updated , but it does not exist. And yet, can anyone explain what the code 417 Expectation failed ? Anyone other than Roy, of course.
The HTTP dictionary of methods and codes is too vague and incomplete to finally arrive at uniform definitions. There is no one, if I am not mistaken, who has found a single, general order and urged the rest to observe it. What is meant by 200 OK in one company can denote completely different information in another, which makes the technology under discussion unpredictable .
If this were the only problem, then I probably would have accepted it and continued to write the RESTful API to this day. However, our list is just being revealed ...
Problem number 2: REST dictionary is not fully supported
Even if we had solved the first problem, we would have encountered the following practical one: most client and server applications do not support all response codes and, in fact, verbs, meaning HTTP methods. For example, most browsers have limited support for PUT and DELETE.
How do we cope with this? One way is to insert a verb denoting the desired method in the form to be sent. This means that in this case the request includes:
- HTTP request method , for example, POST
- The address of the request , for example, / object / list
- A method that we actually mean , for example, DELETE
- Request body , for example, data from the form
The response code situation is no better. Different browsers (and server applications too) often understand these codes differently. For example, having received the code 307 Temporary redirect , one browser may allow the user script to view this response and cancel the action before it is executed. Another browser can simply simply forbid the script to do something. In fact, the only codes that you should not be afraid to handle are 200 OK and 500 Internal server error . In other cases, support for answers varies from “pretty good” to “just awful.” That is why we often have to supplement the body of the response with code that we actually meant .
Even if we could still agree on all of the above, and still magically fixed everything connected to the Internet, but not adapted to the REST software - we still run into another problem.
Problem number 3: The REST dictionary is not saturated enough
A dictionary consisting only of HTTP methods and response codes is too limited to effectively transmit and receive the various information needed by all applications. Imagine that we have created an application from which we want to send a “render complete” response to the client. Unfortunately, we cannot do this with the help of HTTP codes, because, firstly, such a code does not exist , and secondly, we cannot create it, since HTTP is not extensible . Minute of frustration. I think we will again have to insert what we mean in the body of the answer.
Also, the problem is that we have more than one dictionary, we have three of them! Response codes are numeric values (200, 201, 500) that differ from the representation of the request methods (GET, POST, PUT, etc.), and the response body is in JSON format. Performing REST transactions is like sending a letter in English to China and getting a Morse code from there. All these difficulties are a major source of confusion and mistakes. Here we go to the next global problem: debugging.
Problem number 4: RESTful API is very difficult to debug
If you have once worked with the REST API, then you probably know that it is almost impossible to debug. In order to understand what happens during a transaction, we have to look at 7 places at once:
- HTTP request method , for example, POST
- The address of the request , for example, / object / list
- A method that we actually mean (in the request body) , for example, DELETE
- Actually, the request body , for example, data from the form
- Answer code , for example, 200 OK
- The code we meant (in the response body) , for example, 206 Partial Content
- Actually, the response body
So now we have not only two very limited vocabulary, but also 7 different points where an error can be covered. The only thing that could further aggravate the situation is if the REST technology were fully tied to one protocol and it would be impossible to use any other communication channel. Actually, it is, and this is our next big problem!
Problem # 5: Typically, RESTful APIs are bound to the HTTP protocol
RESTful API breaks into one of the fundamental laws of good communication: the content of the message must be completely independent of the transmission channel . Their mixing is the path to total confusion.
Constant interweaving of the HTTP protocol and the transmitted information completely deprives us of the possibility of transferring the RESTful API to other communication channels. Porting RESTfulAPI from HTTP to some other data transfer protocol requires completely disentangling and restructuring information from seven different points that we talked about earlier.
Fortunately, there is a good solution that allows you to avoid or minimize all the problems of the RESTful API. Meet
Step forward: JSON-pure API
JSON-pure API handles most of the problems we just covered.
- Uses only one method for transmitting data - usually POST for HTTP and SEND when using Web Sockets
- The transfer mechanism and the contents of the request are completely independent. All errors, warnings and data are transmitted in the request body, in JSON format.
- Only one response code is used to confirm successful transmission, usually it is 200 OK
- The transmission mechanism and the content of the response are completely independent. All errors, warnings and data are transmitted in the body of the response, in JSON format
- It's much easier to debug, because all the data is in one place in an easy-to-read JSON format.
- Easily transfer to any communication channel, such as HTTP / S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH
JSON-pure API appeared as a result of the awareness of developers of the fact that the RESTful API is not particularly friendly to browsers and developers themselves. Separating the message and transfer method makes the JSON-pure API fast, reliable, easy to use, port, and search for errors. Today, if we need, for example, to use the Twitter API, then masochists will choose the RESTful API. The rest will turn to JSON-pure API, or, as it is also called, “Web API”.
Over the past ten years, I was repeatedly asked to use RESTful instead of JSON-pure. The last time I almost had to support the RESTful API was in 2011. To my luck, the back-end team agreed to run the JSON-pure API in parallel with RESTful, simply transferring all of their methods and codes to JSON.
A few months later, all my friends who had previously used RESTful switched to JSON-pure, realizing that this is much more convenient.
Original article: mmikowski.imtqy.com/
Posted by: Michael S. Mikowski
Source: https://habr.com/ru/post/265845/
All Articles