Семинар 3: взаимодействие с API

Изучите три сервиса через их API. Сравните контракты OpenAPI с ответами на реальные HTTP-запросы.


Исходный код сервисов для локального запуска.


Откройте Swagger UI каждого сервиса и изучите все операции: метод и путь, параметры и тело запроса, тело ответа, коды состояния и схемы ошибок. Сравните документацию с ответами на запросы ниже.

Что понадобится

Примеры с read и $'...' рассчитаны на macOS, Linux или WSL. В PowerShell синтаксис переменных и передачи CSV отличается.

1. Сервис предсказаний

  1. Через cURL вызовите GET /v1/models. Запишите идентификаторы доступных моделей и ответ.
  2. Вызовите POST /v1/predict для каждой модели с одинаковыми корректными признаками. Запишите оба запроса и ответа; объясните, чем отличаются предсказания.
  3. Сделайте минимум два запроса с ошибками: с неизвестной моделью (404) и с признаком вне допустимого диапазона или неверного типа (422). Запишите точный запрос, код состояния и тело ошибки.
  4. Повторите характерные успешные и ошибочные запросы с параметром cURL -v. Изучите полный вывод: заголовки запроса и ответа, строку состояния и тело ответа. Определите, какие строки вывела cURL, а какие прислал сервис.

2. Сервис пользователей

  1. Через cURL создайте пользователя запросом POST /v1/user. Запишите запрос, ответ с кодом 201 и полученный user_id.
  2. Получите созданного пользователя через GET /v1/user/{user_id}. Запишите запрос и атрибуты из ответа.
  3. Измените только возраст через PUT /v1/user/{user_id}, затем получите пользователя и запишите результат.
  4. Измените только пол, затем получите пользователя и запишите результат.
  5. Измените возраст и пол одним запросом, затем получите пользователя и запишите результат.
  6. Передайте недопустимый возраст или пол (422) и запросите несуществующего пользователя (404). Запишите каждый запрос и ответ с ошибкой. Для характерных успешных и ошибочных запросов используйте -v и изучите полный вывод, как для сервиса предсказаний.

3. Повторение запросов в программе для проверки API

Используйте Postman или Insomnia. Повторите запросы к сервисам предсказаний и пользователей. Сохраните или опишите для каждого запроса метод, URL, заголовки, тело, код состояния и ответ. Включите создание и получение пользователя, изменение одного атрибута и изменение обоих атрибутов.

4. Сервис обработки CSV

  1. Изучите все три операции в Swagger UI. Вызовите открытый GET /v1/example и сохраните пример CSV.
  2. Получите у преподавателя токен Bearer. Перед записью команд в журнал введите его без отображения на экране командой read -rs TOKEN, затем выполните export TOKEN, чтобы токен был доступен в оболочке журнала. Не включайте токен в сдаваемый файл. Отправьте авторизованный запрос POST /v1/process с телом text/csv. Используйте пример или другой CSV с точными названиями колонок feature1,feature2,feature3 и не более чем 100 строками данных.
  3. Запишите ответ с кодом 202 и значение run_id. Объясните код 202: запрос принят на асинхронную обработку, но результат может быть ещё не готов.
  4. Получите обработанный CSV авторизованным запросом GET /v1/data/{run_id}. Если обработка не завершилась и сервис вернул 404, подождите и повторите запрос. Изучите изменённые значения. После выдачи результат удаляется; сохраните ответ до повторного запроса.
  5. Разберитесь, как cURL передаёт токен Bearer в заголовке Authorization и как параметр --data-binary передаёт тело CSV без преобразования текста. Повторите получение примера, запуск обработки и получение результата через Postman или Insomnia. Для обработки выберите режим передачи исходного тела с типом text/csv, для защищённых операций — авторизацию с токеном Bearer.
curl -i -X POST 'https://seminar03-api.dataprosvet.ru/csv-processor/v1/process' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: text/csv' \
  --data-binary $'feature1,feature2,feature3\n1,2.5,hello\n10,0.75,world\n'

Перед записью команд задайте TOKEN локально, используя токен преподавателя. Подставьте полученный идентификатор обработки в защищённый запрос на получение данных. Перед сдачей удалите токен из подробного вывода cURL, если он там появился.

* Дополнительное задание: нагрузочное тестирование API (+2 балла)

  1. Изучите, что такое нагрузочное тестирование API и какие показатели помогают оценить работу сервиса под нагрузкой.
  2. Выберите одно из трёх API и проведите для него тест с высокой нагрузкой. Укажите инструмент, сценарий запросов, число одновременных клиентов, длительность и интенсивность нагрузки. Тестируйте локально запущенный сервис; общий стенд нагружайте только после согласования с преподавателем.
  3. Подготовьте отчёт: приведите условия теста, число запросов, пропускную способность, время ответа (например, медиану и 95-й процентиль), долю ошибок, наблюдения и выводы.
  4. Отправьте отчёт по выбранному API преподавателю на проверку. За выполненное дополнительное задание начисляются 2 балла.

Что сдавать

Перед запросами запустите запись терминала командой script -q seminar03.log. Выполните в этом терминале команды cURL, затем завершите запись командой exit. В PowerShell используйте Start-Transcript -Path seminar03.log и Stop-Transcript. Файл должен содержать каждую команду и её вывод, включая ошибки и полный вывод характерных запросов с -v. В тот же файл добавьте сведения о запросах и ответах из Postman или Insomnia, объяснение кода HTTP 202 и обработанный CSV. Удалите токен преподавателя из снимков экрана, экспортированных данных и журнала. Сгруппируйте записи по сервисам и подпишите каждый запрос.