Архитектурный дизайн RESTful приложений
При разработке REST API важнейшим требованием является обеспечение клиента информацией о той версии API, с которой он работает. Например, если прикладной интерфейс сайта доступен по адресу http://site.com/api, то данному URL надо добавить v1 (версия первая), т.е. адрес может принять следующий вид http://site.com/api/v1.
Так как сегодня серверная часть приложения, которая по-другому называется back end, разрабатывается те только для web-платформ, но и для мобильных приложений, то Вам необходимо обратить серьезное внимание на версионирование API. И вот почему. При изменениях API, т.е. добавлении какого-либо функционала, либо признание устаревшим другого, web-приложение, разрабатываемое Вами, будет функционировать должным образом.
Однако, того же нельзя сказать, например, о мобильном приложении, установленном на смартфоне пользователя. Ведь пользователь может отказаться от обновлений приложения, и как же тогда быть? Нельзя же позволить, чтобы изменения на стороне сервера, с которым взаимодействует приложение посредством REST API, привели к недоступности сервиса на клиенте пользователя. Да Вы, возможно, и сами не часто обновляете приложения, или же вовсе отключаете их. Вот поэтому нам как разработчикам нужно в обязательном порядке добавлять версию API в URL.
Заметьте, что существуют два подхода в определении версии API: через URL, как было показано выше или через HTTP заголовок Accept:
Accept: application/vnd.myrusakov+json;version=1.0
Все ресурсы в REST, определяемые с помощью URL, являются объектами. Объекты могут быть независимыми:
GET /articles – получить все статьи
GET /articles/1036 – получить конкретную статью по идентификатору 1036
или зависимыми:
GET /articles/1036/comments – получить все комментарии к статье.
Т.е. объект комментариев принадлежит к конкретной статье и поэтому зависит от нее.
В примере выше мы GET запрос возвращает объект статей, статьи и комментариев. Запрос GET -идемпотентный, это означает, сколько бы мы раз не запрашивали URL /articles/1036, он всегда будет возвращать одно и то же. Успешный запрос должен возвратить объект статьи и HTTP код статуса 200 OK. В случае же возникновения ошибки могут быть возвращены следующие ответы: 404 (не найдено), 400 (неверный запрос) или ошибка из группы 500-599 (ошибки сервера).
Теперь рассмотрим метод POST, с помощью которого можно создать новую статью.
Запрос:
POST /articles
Тело запроса:
{
"title": "Версионирование REST API",
"content": "Содержание статьи"
}
Как видно, POST запрос не является идемпотентным, так как при отправке одного и того же запроса, будет создаваться новая статья, несмотря на то, что содержание одно и тоже. Правда идентификатор объекта статьи будет другим.
После успешного завершения запроса должен, опять же быть возвращен статус 200 OK. А тело ответа может быть следующего формата:
{
"id": 1,
"title": "Версионирование REST API",
"content": "Содержание статьи"
}
Также мы могли бы вернуть статус 201 (Created), информирующий о том, что объект создан, и заголовок Location с URL идентификатором вновь созданной статьи.
Следующий на очереди метод – PUT. Его используют для того, чтобы обновить какой-либо объект – запись в базе данных, например. При отправке этого запроса, тело запроса должно содержать обновленные данные для записи, на которую указана ссылка в URL. Пример:
Запрос:
PUT /articles/1
Тело запроса:
{
"id": 1,
"title": "Версионирование REST API - Продолжение",
"content": "Эта статья является продолжением предыдущей статьи"
}
Возможный ответ в случае успеха:
Status: 200 OK
Location: /articles/1
И последний запрос – это DELETE
DELETE /articles/1 – удаляет статью с идентификатором 1
В случае успешного завершения операции, возвращает статус 200 OK вместе с телом ответа, которое содержит информацию о статусе объекта. Например, если Вы не удаляете объект (под которым понимается статья, комментарии), а помечаете его как удаленный, повторные запросы DELETE должны возвращать статус 200 OK с той же информацией указанной выше. Но, если Вы удалили статью или комментарий, или какой-либо другой объект из базы данных полностью, то последующие запросы по этому адресу должны возвращать код 404 (не найдено).
Таким образом, версионирование в REST API играют важнейшую роль, определяя короткий, понятный и недвусмысленный интерфейс взаимодействия с приложением.
-
Создано 24.10.2017 12:43:01
-
Михаил Русаков
Комментарии (0):
Для добавления комментариев надо войти в систему.
Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.