Лабораторная работа №7 · REST API службы доставки

01 · Процесс

Что происходит, когда вы отправляете запрос

Swagger UI помогает составить HTTP-запрос и отправить его. Сам API работает на сервере: проверяет данные, выполняет действие и возвращает ответ.

Шаг 1Вы задаёте запросВыбираете действие и вводите нужные данные в Swagger UI.

Шаг 2Браузер отправляет HTTPВ запросе есть метод, адрес и, когда нужно, JSON.

Шаг 3API обрабатывает данныеСервер проверяет запрос и выполняет операцию.

Шаг 4Вы читаете ответПроверьте код HTTP и тело ответа. Панель обновит прогресс.

Главная привычка: после каждого запроса смотрите не только на нажатие Execute, но и на код ответа и данные, которые вернул сервер.

02 · Запрос и ответ

На что смотреть в Swagger UI

У каждого запроса есть действие (HTTP-метод) и адрес. Некоторые запросы передают данные в JSON. Ответ содержит код HTTP и тело — часто тоже в JSON.

Метод	Что делает в этой работе	Пример
`GET`	Получает данные, не меняя отправление.	`GET /shipments`
`POST`	Создаёт отправление или выполняет действие.	`POST /shipments`
`PATCH`	Изменяет часть данных отправления.	`PATCH /shipments/{shipment_id}`

200Запрос выполнен.

201Новое отправление создано.

422Данные запроса не прошли проверку.

Если получили ошибку, прочитайте ответ сервера: он поможет найти поле или значение, которое нужно исправить.

Пример тела запроса в формате JSON в Swagger UI — JSON перед отправкой: структура корректна, но одно значение намеренно не подходит API.

03 · Начало работы

Подключитесь к учебному стенду

Откройте документацию API и панель заданий.
Зарегистрируйтесь, указав фамилию, имя и группу. Сохраните выданный токен: он даёт доступ к вашей учебной сессии.
После регистрации стенд подключит вас автоматически. Если вы уже регистрировались, вставьте сохранённый токен — подключение тоже произойдёт автоматически.
Используйте одну сессию: она действует 24 часа. Повторная регистрация создаёт новые учебные данные, а прогресс прежней сессии остаётся отдельно.

Не публикуйте токен и не передавайте его другим людям. После обновления страницы вставьте тот же токен, чтобы продолжить в своей сессии.

Панель регистрации и прогресса лабораторной — Панель показывает четыре задания и автоматически обновляется после действий в API.

04 · Практика

Выполните четыре задания

Первое задание проведёт вас по основному циклу. В следующих сначала попробуйте решить задачу самостоятельно; подсказки можно открыть в любой момент.

Отмените отправление

Иванов Иван Иванович отказался от посылки в ПВЗ на ул. Гузовского, 16.

Найдите ПВЗ по адресу в справочнике, затем отправление Иванова в списке.
Откройте действие отмены и передайте ID найденного отправления.
Проверьте код ответа и новый статус отправления.

Готово, когда: сервер подтвердил отмену этого отправления.

Посмотрите состояние и отслеживание

Найдите отправление Петрова Петра Петровича и определите, какое событие произошло последним.

Откройте историю и сравните значения occurred_at. Последним произошло событие с самым поздним временем. История описывает события, а status показывает текущее состояние.

После просмотра истории ответьте на вопрос в панели. Если ошиблись, можно выбрать другой вариант.

Готово, когда: история нужного отправления просмотрена и выбран ответ с самым поздним временем события.

Измените доставку

Сидоров Сидор Сидорович просит перенаправить посылку в ПВЗ на ул. Ленинского комсомола, 23к3.

Готово, когда: у отправления Сидорова указан нужный пункт выдачи.

Подсказка 1 · где найти сведения

Сверьте список отправлений и справочник ПВЗ. Нужны ID отправления и ID пункта на указанной улице.

Подсказка 2 · какое действие

Для частичного изменения данных используется PATCH /shipments/{shipment_id}.

Подсказка 3 · какие данные

Подставьте ID отправления в адрес запроса. В JSON передайте поле pickup_point_id с ID нужного пункта.

Подсказка 4 · пример JSON

Сверьте ID с текущим справочником и после отправки проверьте ответ.

{
  "pickup_point_id": "cheb-003"
}

Создайте отправление и исправьте запрос

Создайте отправление для нового получателя в ПВЗ на ул. Водопроводная, 22. Сначала сервер должен сообщить об ошибке в значении способа доставки; затем исправьте его.

Смысл этого задания: корректный JSON может содержать недопустимое значение. Прочитайте ответ API, найдите поле с ошибкой и исправьте только его.

Готово, когда: сначала получен HTTP 422 из-за delivery_method, затем HTTP 201 для отправления в нужный ПВЗ.

Подсказка 1 · где найти адрес и ID

Откройте справочник пунктов выдачи и найдите ID ПВЗ на ул. Водопроводная, 22.

Подсказка 2 · какой запрос

Новое отправление создаётся через POST /shipments.

Подсказка 3 · какие поля

Укажите recipient_name, delivery_method и pickup_point_id. Сначала используйте неподдерживаемый способ доставки, затем замените его допустимым.

Подсказка 4 · пример ошибки и исправления

Сначала отправьте синтаксически корректный JSON с неверным способом доставки:

{
  "recipient_name": "Новый Получатель",
  "delivery_method": "teleport",
  "pickup_point_id": "cheb-002"
}

Получив HTTP 422, исправьте поле и повторите запрос:

{
  "recipient_name": "Новый Получатель",
  "delivery_method": "pickup_point",
  "pickup_point_id": "cheb-002"
}

Перед отправкой сверьте ID пункта выдачи со справочником.

HTTP 422 и сообщение API о недопустимом значении delivery_method — HTTP 422: сервер указывает на поле delivery_method и объясняет, какие значения допустимы.

Ответ HTTP 201 после исправления запроса — После исправления поля API создаёт отправление и возвращает HTTP 201 Created.

Завершение

Как понять, что работа выполнена

Панель отметит задания по результатам запросов. Когда будут выполнены все четыре критерия, стенд покажет, что лабораторная сдана. Отчёт и скриншоты от студента не требуются.