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 you have read our privacy policy.

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