16

Объясните, пожалуйста, простым языком (желательно с простым примером, чтобы наверняка) что такое REST API, REST приложение, а также почему иногда добавляют суффикс «full».

1 ответ 1

29

REST - одна из околопрограммистских штук, которую объяснить сложнее всего на свете. Поэтом это будет не полноценное объяснение, а просто рассказ с примерами. Лучше, к сожалению, у меня просто не получится.

Вы, наверное, уже встречали расшифровку Representational State Transfer. Если совсем грубо, то это явная передача состояния приложения с помощью HTTP (звучит коряво, да? сделаем вид, что этого предложения вообще не было). В общем и целом это просто концепция оформления интерфейса для клиентов API.

Представим, что некоторый магазин решил завести свое API. Для этого программист выделил поддомен http://api.maga.zin/v1 и предлагает всем слать туда запросы:

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

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

Несмотря на то, что такая штука может работать, автоматизироваться она не будет вообще. Какая операция уходит наружу - на чтение, обновление, создание или удаления? Можно ли ее повторять? К какому ресурсу она относится? Можно ли легко локализовать доменную область ошибки в случае ее возникновения? На все вопросы можно ответить отрицательно, даже на те, которые не подразумевают булевого ответа; это - API нулевого уровня REST, или API, которое с REST вообще никак не связано.

Однако этот пример высосан из пальца. Куда чаще все-таки по URL можно определить, с чем ведется работа, например, тот же вконтактик с его audio.get дает возможность определить, что клиент будет получать именно данные об аудио. Это первый уровень зрелости REST - разбиение API на отдельные ресурсы, с которыми ведется работа. Только обычно, конечно, ресурсы разбиваются иным образом:

  • /audio - коллекция аудиозаписей
  • /audio/1234 - отдельный ресурс аудиозаписи с идентификатором 1234

Здесь я хочу ненадолго остановиться и обратить внимание на то, что работа (в правильном API) ведется не как с "урлом, по которому можно получить данные", а как с двумя ресурсами. Коллекцию можно отфильтровать, отсортировать и получить из нее отдельную вырезку (страницу), можно создать новый элемент (новый отдельный ресурс), в ряде случаев - заменить или удалить целиком, а конкретный ресурс можно получить (возможно, тоже с фильтрацией, если он может быть большим), заменить или удалить.

В контексте примера с магазином запросы уже могут выглядеть вот так:

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

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

Однако само разбиение на ресурсы не позволяет полноценно отличить одну операцию от другой. Для этого REST предлагает использовать HTTP-методы: POST (create), GET (read), PUT (update), DELETE. Если их использовать, то запрос однозначно сообщает серверу, чего он хочет: GET /account/123 означает необходимость получить ресурс "аккаунт" с идентификатором 123, DELETE /account означает необходимость удалить все имеющиеся аккаунты. Использование HTTP-методов соответствует уровню зрелости REST 2. Когда вы слышите про REST API, вам, скорее всего, рассказывают про этот кейс - про деление на ресурсы и передачу конкретной операции через HTTP-метод.

И, наконец, есть третий уровень зрелости REST, но он (еще) практически нигде не используется. На этом уровне API отдает не только ресурсы, но и подсказки по управлению этими ресурсами. Если представить следующий листинг:

/pair?page=12&size=2

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

то здесь абсолютно непонтяно, как сослаться на пару {"x": 12, "y": 13}, чтобы удалить ее; также непонятно, какая это страница, есть ли следующая, и как перейти на предыдущую. Поэтому API может предоставлять эти данные:

/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 не указывает четкой спецификации, как должны быть сделаны эти подсказки, но есть широкоупотребимый HAL + ALPS для описания самой схемы API (т.е. для описания того, какие ресурсы и по какому адресу лежат). Эти подсказки позволяют клиенту - человеку или программе - обнаружить ресурсы, не зная об их существовании на момент запроса.

Ну так вот, что такое REST? REST - это парадигма организации API, которая подразумевает (помимо прочего) четкое разбиение на ресурсы и вызов операции с помощью конкретного HTTP-метода. Но - только в пределах этого рассказа и перетолков сугубо вебдевелоперского характера: строго говоря, REST - это более строгий набор требований, из которого и происходит необходимость работать таким образом. Но когда вы видите в интернете "REST API" - это про четкое разделение на ресурсы, про операции через HTTP-методы, про правильный Content-Type в зависимости от Accept, про выражение ошибок через коды HTTP и единообразность представления этих ресурсов. А суффикс (который на самом деле ful, а не full) означает только превращение слова в прилагательное, REST - парадигма, RESTful API - API, соответствующий парадигме.

Что она вообще дает? Во-первых, API становится свежим и приятно пахнет - с ним легко и просто работать, потому что вы знаете, что от него ожидать, что ресурсы всегда будут представлены в одном и том же виде, и знаете это не только вы, но и любой API-клиент (и, более того, можно соорудить api-клиент, не зная конечных ресурсов); во-вторых, эта логика относится не только к конкретному API, но и ко всем API, построенным по парадигме REST. Поэтому однажды освоившись с API github освоиться с любым другим REST API не составит никакого труда.

На тот случай, если я стал писать слишком обобщенно и гуманитарно - дополнительные ссылки:

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

Ваш ответ

By clicking “Отправить ответ”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.