RESTful API is a big lie

From a translator:
I first tried to translate an article of such a volume and IT-topics, I will gladly read your comments and comments. As for the article itself: I do not agree with the author, at least because, in fact, he replaces REST with ... REST (!!!), but in a slightly different frame. However, despite the fact that the article presents a lot of obvious things, it seemed to me worthy of discussion on Habré.

Why you should bury this popular technology


RESTful api is wonderful, right?

If over the past 10 years you read a summary of web developers, then it’s excusable for you to think that the RESTful API is a kind of divine gift that has come down to us from heaven. The 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 ...

Where did REST come from?

This technology became popular when it was described in detail and introduced by Roy Fielding in his doctoral dissertation entitled Architectural Styles and the Design of Network-based Software Architectures 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 style of software architecture for building distributed, scalable web services. Roy advocated using standard HTTP methods to give requests a specific meaning.

Thus, these HTTP requests will have different semantic load in REST:
  • Get / object / list
  • POST / object / list
  • PUT / object / list

Above are just some types of queries, but their entire list: 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 either the client or server applications.

Roy also claimed that HTTP response codes would help determine the meaning of the responses themselves. There are about 38 response codes and below you can see a list of them. I have abbreviated the names of some for convenience:


So, one transaction for such an API will consist of at least the following:
  • Request method e.g. GET
  • Request path , e.g. / object / list
  • Request body , e.g. form
  • Response code , for example, 200 OK
  • Response body , for example, JSON data

Many responded 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 can be more complicated and we will discuss the reasons for this. However, we will omit the complicating factors that are associated with networks and caching, as these issues are also relevant for other technologies.

RESTful API is actually 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 our eyes and admit that the concept of a RESTful API is one of the worst ideas that has ever existed in web development. No, I don’t argue, Roy is a great guy and, of course, he had a lot of cool ideas ... However, I'm not sure if the RESTful API is on their list.

Soon we will look at another, more correct solution for building an API, but before doing this, we should understand the 5 main problems of a RESTful API that make it expensive, vulnerable to errors and inconvenient. Let's get started!

Problem # 1: There is still no general agreement on what a RESTful API is.

It is unlikely that anyone thought about why this technology is called “RESTful”, and not “RESTpure”? ( Translator's note: pure - clear, understandable ) And because no one can decide what all request methods, response codes, bodies, etc. are like.

For example, when should we use the 200 OK code ? Can we use it to confirm a successful update of the record, or should we use the code 201 Created ? Apparently, you need to use the 250 Updated code , but it does not exist. And yet, can anyone explain what the 417 Expectation failed code means ?! Anyone other than Roy, of course.

The dictionary of HTTP methods and codes is too vague and incomplete to finally come to uniform definitions. There is no one, if I am not mistaken, who found a single, general order and urged the rest to observe it. What is meant by 200 OK in one company may indicate completely different information in another, which makes the technology under discussion unpredictable .

If this were the only problem, then I probably would have resigned myself and continued to write the RESTful API to this day. However, our list is only being revealed ...

Problem # 2: REST dictionary is not fully supported

Even if we solved the first problem, we would have faced 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 deal with this? One way is to insert a verb denoting the desired method into the form you submit. This means that in this case, the request includes:

  • HTTP request method , for example, POST
  • Request address , e.g. / object / list
  • The method we actually mean , for example, DELETE
  • Request body , for example, data from a form

The situation with response codes is no better. Different browsers (and server applications too) often understand these codes differently. For example, if you receive the 307 Temporary redirect code , one browser may allow the user script to review this response and cancel the action before it is executed. Another browser may simply prevent the script from doing anything. In fact, the only codes that you can not be afraid of processing are 200 OK and 500 Internal server error . In the remaining cases, support for the answers ranges from "pretty good" to "just awful." That is why we often have to supplement the response body with the code that we actually meant .

Even if we could still coordinate all of the above, and still magically fix everything connected to the Internet, but not REST-adapted, we will still face another problem.

Problem # 3: REST Dictionary Not Enough

A dictionary consisting only of HTTP methods and response codes is too limited for the efficient transmission and reception of a variety of information needed by all applications. Imagine that we created an application from which we want to send the client a “render complete” response. Unfortunately, we cannot do this using HTTP codes, because, firstly, such a code does not exist , and secondly, we cannot create it, since HTTP is not extensible . A moment of disappointment. 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! Answer codes are numerical values ​​(200, 201, 500) that differ from the representationrequest 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 receiving a response from a morse code from there. All of these difficulties are a major source of confusion and error. So we moved on to the next global problem: debugging.

Problem # 4: RESTful API is very difficult to debug

If you have ever worked with a REST API, then you are probably aware that it is almost impossible to debug it. In order to understand what happens during the transaction, we have to look at 7 places at once:

  • HTTP request method , for example, POST
  • Request address , e.g. / object / list
  • The method we actually mean (in the request body) , for example, DELETE
  • Actually, the request body , for example, data from the form
  • Response code , for example, 200 OK
  • The code we meant (in the body of the response) , for example, 206 Partial Content
  • Actually, the response body

So now we have not only two very limited dictionaries, but also 7 different points at which the error may lie. The only thing that could further aggravate the situation is if REST technology were completely 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.

The RESTful API shatters one of the fundamental laws of good communication: the content of the message must be absolutely independent of the transmission channel . Mixing them is the way to complete confusion.

The 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 a RESTfulAPI from HTTP to some other data transfer protocol requires complete unraveling and restructuring of information from seven different points that we talked about earlier.

Fortunately, there is a good solution that avoids or minimizes all the problems of the RESTful API. Meet me!

Step forward: JSON-pure API

The JSON-pure API handles most of the problems we just covered.

  • Uses only one method for data transfer - usually POST for HTTP and SEND in case of using Web Sockets
  • The transmission 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 200 OK
  • The transmission mechanism and the content of the response are completely independent. All errors, warnings and data are transmitted in the response body, in JSON format
  • Much easier to debug, because all the data is in one place in an easy-to-read JSON format
  • Easily migrate to any communication channel, for example, HTTP / S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH

The JSON-pure API appeared as a result of the realization by developers of the fact that the RESTful API is not particularly friendly to browsers and developers themselves. Separating the message and the transmission method makes the JSON-pure API fast, reliable, easy to use, port and find errors. Today, if we need to use, for example, the Twitter API, masochists will choose a RESTful API. The rest will turn to the JSON-pure API, or, as it is also called, the "Web API".

Over the past ten years, I have been asked more than once to use RESTful instead of JSON-pure. The last time I almost had to support the RESTful API was in 2011. Fortunately, the back-end team agreed to run the JSON-pure API in parallel with RESTful, simply transferring all of its methods and codes to JSON.
A few months later, all of my friends who had previously used RESTful switched to JSON-pure, realizing that it was much more convenient.

Original article:
Posted by Michael S. Mikowski

Also popular now: