Продолжая разбирать актуальные для начинающих системных и бизнес-аналитиков темы по основам работы распределенных систем и межсистемной интеграции, сегодня рассмотрим, как система с REST API отвечает на запросы клиента. Рассмотрим наиболее частые коды HTTP-ответов на GET, POST, PUT, PATCH и DELETE-запросы на примере интернет-магазина.
GET-и POST-запросы и ответы на них
В качестве примера распределенной системы возьмем интернет-магазин. Предположим, менеджер интернет-магазина хочет просмотреть ТОП-10 самых дорогих игрушечных машин белого цвета и добавить новую туда новую игрушку, если там нет аналогичной. В системе с REST API это будет выглядеть следующим образом: сперва менеджер отправляет с клиентского компьютера HTTP-запрос GET к конечной точке по URL-адресу http://site-domain-name/products/toys?category=car&color=white&count=10&view=list&sort=pricedown. В этом запросе http://site-domain-name/products/toys — это URL-адрес ресурса, т.е. маршрут (route), а сам HTTP-метод запроса — это конечная точка (endpoint), который является пунктом доступа к системе извне. Параметры фильтрации и сортировки данных идут в заголовке запроса после вопросительного знака (?). В частности, выражение category=car задает, что нужны только машины, т.е. те товары, которые относятся к этой категории. Следующие параметры, разделенные знаком амперсанда (&), уточняют цвет (color=white), количество возвращаемых результатов (count =10), вариант их представления (view=list) и сортировку вывода (sort=pricedown).
В ответ система возвращает клиенту список товаров, отвечающих заданным условием, включив в ответное сообщение статус выполнения посланного HTTP-запроса со статусом 200 (OK), который означает успешное выполнение запроса: данные в системе есть и у пользователя есть право их чтения. В отличие от SOAP, REST может возвращать данные в любом формате (HTML, XML, JSON), но чаще всего это человеко-читаемый текстовый формат JSON (JavaScript Object Notation) на основе JavaScript. Подробнее о сходствах и различиях SOAP и REST, а также их сравнении с другими стилями межсистемной интеграции по API я писала здесь.
Вообще протокол HTTP поддерживает следующие группы кодов ответа, которые показывают состояние выполнения запроса, был ли он выполнен успешно, или возникла какая-либо ошибка:
- информационные коды имеют номера от 100 до 199;
- коды успешного выполнения запросов имеют номера от 200 до 299;
- перенаправления кодируются номерами от 300 до 399;
- клиентские ошибки имеют коды от 400 до 499;
- ошибки сервера кодируются номерами от 500 до 599.
Примечательно, что некоторые коды могут не поддерживаться старыми версиями HTTP-протокола.
Просмотрев возвращенный список товаров, менеджер решает добавить новый товар, послав HTTTP-запрос POST к конечной точке http://site-domain-name/products/toys. Здесь параметры нового добавляемого товара передаются не в заголовке, а в теле HTTP-запроса. Если у пользователя с ролью «Менеджер» есть право добавлять новые товары, т.е. создавать ресурсы, в ответ система возвратит данные с идентификатором вновь созданного ресурса и HTTP-кодом успешного ответа со статусом 201 (Created), т.к. изначально целевой ресурс не имел отправляемой сущности и POST-запрос создал её. Новый ресурс возвращается в теле сообщения, его местоположение представляет собой URL-адрес запроса или содержимое заголовка Location. Например, http://site-domain-name/products/toys/4689, где 4689 – это идентификатор только что добавленного товара. Иначе система вернет ответ с кодом 401 (Unauthorized), который означает статус ошибки и указывает, что запрос не был выполнен из-за отсутствия у клиента прав, т.е. действующих учётных данных для манипуляций с целевым ресурсом.
Основы архитектуры и интеграции информационных систем
Код курса
OAIS
Ближайшая дата курса
20 января, 2025
Продолжительность
16 ак.часов
Стоимость обучения
36 000 руб.
Запросы PUT, POST и DELETE
Когда менеджер захочет изменить характеристики ранее созданного товара, он отправит PUT-запрос к конечной точке http://site-domain-name/products/toys/4689 с данными для полного обновления этого ресурса в теле запроса. Можно использовать и PATCH-запрос для частичного обновления данных, однако, здесь нужно вспомнить про различия между этими методами в плане идемпотентности. PATCH может как идемпотентным или не быть, в отличие от PUT-запроса, который всегда идемпотентен. Напомним, операция считается идемпотентной, если её повторное выполнение приводит к тому же результату, что и первичное. PUT-запрос перезапишет автоинкрементируемое поле при обращении к ресурсу, а PATCH может и не перезаписать. Разумеется, чтобы выполнить операцию изменения, менеджер должен иметь права на выполнение этой операции. Если целевой ресурс содержит отправляемую сущность (в нашем случае игрушку с идентификатором 4689) и ее характеристики были успешно обновлены согласно данным в теле запроса, в HTTP-коде ответа будет статус 200 (OK) или 204 (No Content), который указывает, что запрос успешно выполнено, но клиенту не нужно уходить со своей текущей страницы. Иначе, если у менеджера нет прав на изменение характеристик товара, система вернет ответ с кодом 401 (Unauthorized).
Наконец, предположим, что менеджер решил удалить из каталога игрушку с идентификатором 4689. Для этого надо отправить HTTP-запрос DELETE на конечную точку http://site-domain-name/products/toys/4689. Если у менеджера есть права на удаление ресурсов, метод DELETE может вернуть следующие коды состояния ответа:
- 200 (OK) — удаление успешно выполнено;
- 202 (Accepted) – запрос получен, но еще не обработан, но он будет успешно выполнен;
- 204 (No Content) — удаление успешно выполнено, клиенту не нужно уходить со своей текущей страницы, тело ответа отсутствует.
При отсутствии у менеджера прав на операцию удаления указанного товара, система вернет ответ с кодом 401 (Unauthorized). Подробнее про процедуры аутентификации и авторизации в веб-приложениях читайте в моей новой статье.
Покажем некоторые операции этого взаимодействие пользователя с REST API системой в виде BPMN-диаграммы.
Однако, на самом деле в веб-приложениях все описанные операции выполняются чуть сложнее. Как это работает, рассмотрим в следующий раз. А пока предлагаем вам проверить, как вы усвоили материалы по REST API в открытом интерактивном тесте.
А подробнее познакомиться с основами архитектуры и интеграции информационных систем вам помогут курсы Школы прикладного бизнес-анализа в нашем лицензированном учебном центре обучения и повышения квалификации системных и бизнес-аналитиков в Москве:
- Основы архитектуры и интеграции информационных систем
- Разработка ТЗ на информационную систему по ГОСТ и SRS
Источники
