#rest #терминология
Объясните, пожалуйста, простым языком (желательно с простым примером, чтобы наверняка)
что такое 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
Комментариев нет:
Отправить комментарий