REST API, REST applications: what is it and what is it for? (+ full)

Question:

Please explain in simple language (preferably with a simple example, to be sure) what a REST API, a REST application is, and why the "full" suffix is ​​sometimes added.

Answer:

REST is one of the hardest things to explain in the world around programming. Therefore, this will not be a full-fledged explanation, but just a story with examples. Better, unfortunately, I simply will not succeed.

You've probably already met the transcript of Representational State Transfer. Roughly speaking, this is an explicit transfer of application state using HTTP (sounds clumsy, right? Let's pretend that this proposal did not exist at all). In general, this is just a concept of interface design for API clients.

Let's imagine that some store decided to create their own API. To do this, the programmer has selected the subdomain http://api.maga.zin/v1 and invites everyone to send requests there:

POST http://api.maga.zin/v1 HTTP/1.1

{
    "action": "getProducts",
    "parameters": {
        "page": 3,
        "size": 50,
        "sort": [ {
            "field": "price",
            "direction": "asc"
        } ]
    }
}

Despite the fact that such a thing can work, it will not be automated at all. What operation goes outside – read, update, create or delete? Can you repeat it? What resource does it belong to? Is it possible to easily localize the domain scope of an error if it occurs? All questions can be answered negatively, even those that do not imply a boolean answer; it is a REST level zero API, or API that has nothing to do with REST at all.

However, this example is sucked from the thumb. Much more often, you can still use the URL to determine what the work is being done, for example, the same in the contact with its audio.get makes it possible to determine that the client will receive exactly the audio data. This is the first level of REST maturity – breaking the API into separate resources that you work with. Only usually, of course, resources are broken in a different way:

  • / audio – collection of audio recordings
  • / audio / 1234 – separate audio recording resource with ID 1234

Here I want to stop for a while and draw your attention to the fact that the work (in the correct API) is carried out not as with a "URL where you can get data", but as with two resources . A collection can be filtered , sorted and a separate cut (page) can be obtained from it, a new element can be created (a new separate resource), in some cases, replaced or deleted entirely, and a specific resource can be obtained (possibly also with filtering, if it can be large), replace or delete.

In the context of the store example, the requests might look like this:

POST http://api.maga.zin/v2/product?act=edit&id=12 HTTP/1.1

{
    "name": "Иисусья тряпка",
    "price": 123,
    "quantity": 12
}

However, the division into resources itself does not allow to fully distinguish one operation from another. To do this, REST suggests using HTTP methods: POST (create), GET (read), PUT (update), DELETE. If you use them, the request unambiguously tells the server what it wants: GET / account / 123 means the need to get the resource "account" with the identifier 123, DELETE / account means the need to delete all existing accounts. Using HTTP methods corresponds to REST 2 maturity level 2. When you hear about the REST API, you are most likely told about this case – about dividing into resources and passing a specific operation through an HTTP method.

And finally, there is a third level of REST maturity, but it is (yet) hardly used anywhere. At this level, the API provides not only resources, but also hints on how to manage these resources. If you imagine the following listing:

/pair?page=12&size=2

[ 
    {
        "x": 12,
        "y": 13
    },
    {
        "x": 25,
        "y": 26
    }
]

then it is completely unclear how to refer to the pair {"x": 12, "y": 13} to remove it; it is also unclear which page it is, whether it is next, and how to go to the previous one. Therefore, the API can provide this data:

/pair?page=12&size=2

{
    "content": [ 
        {
            "x": 12,
            "y": 13,
            "link": "/pair/12-13"
        },
        {
            "x": 25,
            "y": 26,
            "link": "/pair/25-26"
        }
    ],
    "pagination": {
        "currentPage": 12,
        "nextPage": null,
        "previousPage": "/pair?page=11&size=2",
        "totalPages": 12,
        "totalElements": 24
    }
]

REST does not explicitly specify how these hints should be made, but there is a widely used HAL + ALPS to describe the API schema itself (i.e., to describe which resources are at which address). These hints allow a client – a person or a program – to discover resources without knowing they exist at the time of the request.

So what is REST? REST is a paradigm for organizing an API that involves (among other things) explicitly resource partitioning and invoking an operation using a specific HTTP method. But – only within the limits of this story and the re-interpretations of a purely web-development nature: strictly speaking, REST is a more stringent set of requirements , from which the need to work in this way arises. But when you see "REST API" on the Internet, it's about a clear division into resources, about operations via HTTP methods, about the correct Content-Type depending on Accept, about expressing errors through HTTP codes and the uniformity of presentation of these resources. And the suffix (which is actually ful, not full) only means converting a word into an adjective, REST is a paradigm, RESTful API is an API that matches a paradigm.

What does she give at all? First, the API becomes fresh and smells good – it's easy and simple to work with, because you know what to expect from it, that resources will always be presented in the same form, and you know this not only you, but everyone API client (and, moreover, you can build an api client without knowing the final resources ); second, this logic applies not only to a specific API, but to all APIs built on the REST paradigm. Therefore, once familiar with the github API, getting comfortable with any other REST API will not be difficult.

In case I began to write too general and humanitarian – additional links:

https://habrahabr.ru/company/hexlet/blog/274675/ http://martinfowler.com/articles/richardsonMaturityModel.html

Scroll to Top