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