Семинар 3: взаимодействие с API
Изучите три сервиса через их API. Сравните контракты OpenAPI с ответами на реальные HTTP-запросы.
Исходный код сервисов для локального запуска.
- Сервис предсказаний — путь к Swagger UI:
/ml-service/docs. Возвращает список двух детерминированных моделей и строит предсказание по трём признакам: целомуfeature1(0–100), числуfeature2(0–1) и строкеfeature3(1–32 символа). Модельlinear-scoreвозвращает число;risk-labelвозвращаетlow,mediumилиhigh. - Сервис пользователей — путь к Swagger UI:
/user-service/docs. Создаёт пользователей в SQLite с возрастом от 6 до 90 лет и поломmaleилиfemale, возвращает идентификатор, позволяет получить пользователя, изменить один или оба атрибута и удалить пользователя. - Сервис обработки CSV — путь к Swagger UI:
/csv-processor/docs. Принимает CSV с авторизацией. Файл должен содержать колонкиfeature1,feature2иfeature3и не более 100 строк данных. Сервис прибавляет 10 к значениям первых двух числовых колонок и оставляет первый символ значения третьей. Результат можно получить один раз по идентификатору обработки.
Откройте Swagger UI каждого сервиса и изучите все операции: метод и путь, параметры и тело запроса, тело ответа, коды состояния и схемы ошибок. Сравните документацию с ответами на запросы ниже.
Что понадобится
- cURL. Проверьте установку командой
curl --version. В macOS cURL обычно уже есть; при необходимости установите его через Homebrew. В Windows 10/11 используйтеcurl.exeили скачайте сборку с официальной страницы cURL для Windows. В Linux установите пакетcurlчерез пакетный менеджер дистрибутива; варианты загрузки для Linux перечислены на сайте проекта. - Программа для проверки API. Установите одну на выбор: Postman или Insomnia.
- Запись команд и вывода терминала. В macOS команда
scriptуже доступна. В Linux она входит в пакетutil-linux: описание и ссылка на пакет. В Windows для выполнения приведённых ниже команд в том же синтаксисе установите WSL и используйтеscriptвнутри Linux. В обычном PowerShell запись сеанса выполняет встроенная команда Start-Transcript.
Примеры с read и $'...' рассчитаны на macOS, Linux или WSL. В PowerShell синтаксис переменных и передачи CSV отличается.
1. Сервис предсказаний
- Через cURL вызовите
GET /v1/models. Запишите идентификаторы доступных моделей и ответ. - Вызовите
POST /v1/predictдля каждой модели с одинаковыми корректными признаками. Запишите оба запроса и ответа; объясните, чем отличаются предсказания. - Сделайте минимум два запроса с ошибками: с неизвестной моделью (404) и с признаком вне допустимого диапазона или неверного типа (422). Запишите точный запрос, код состояния и тело ошибки.
- Повторите характерные успешные и ошибочные запросы с параметром cURL
-v. Изучите полный вывод: заголовки запроса и ответа, строку состояния и тело ответа. Определите, какие строки вывела cURL, а какие прислал сервис.
2. Сервис пользователей
- Через cURL создайте пользователя запросом
POST /v1/user. Запишите запрос, ответ с кодом 201 и полученныйuser_id. - Получите созданного пользователя через
GET /v1/user/{user_id}. Запишите запрос и атрибуты из ответа. - Измените только возраст через
PUT /v1/user/{user_id}, затем получите пользователя и запишите результат. - Измените только пол, затем получите пользователя и запишите результат.
- Измените возраст и пол одним запросом, затем получите пользователя и запишите результат.
- Передайте недопустимый возраст или пол (422) и запросите несуществующего пользователя (404). Запишите каждый запрос и ответ с ошибкой. Для характерных успешных и ошибочных запросов используйте
-vи изучите полный вывод, как для сервиса предсказаний.
3. Повторение запросов в программе для проверки API
Используйте Postman или Insomnia. Повторите запросы к сервисам предсказаний и пользователей. Сохраните или опишите для каждого запроса метод, URL, заголовки, тело, код состояния и ответ. Включите создание и получение пользователя, изменение одного атрибута и изменение обоих атрибутов.
4. Сервис обработки CSV
- Изучите все три операции в Swagger UI. Вызовите открытый
GET /v1/exampleи сохраните пример CSV. - Получите у преподавателя токен Bearer. Перед записью команд в журнал введите его без отображения на экране командой
read -rs TOKEN, затем выполнитеexport TOKEN, чтобы токен был доступен в оболочке журнала. Не включайте токен в сдаваемый файл. Отправьте авторизованный запросPOST /v1/processс теломtext/csv. Используйте пример или другой CSV с точными названиями колонокfeature1,feature2,feature3и не более чем 100 строками данных. - Запишите ответ с кодом 202 и значение
run_id. Объясните код 202: запрос принят на асинхронную обработку, но результат может быть ещё не готов. - Получите обработанный CSV авторизованным запросом
GET /v1/data/{run_id}. Если обработка не завершилась и сервис вернул 404, подождите и повторите запрос. Изучите изменённые значения. После выдачи результат удаляется; сохраните ответ до повторного запроса. - Разберитесь, как 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 балла)
- Изучите, что такое нагрузочное тестирование API и какие показатели помогают оценить работу сервиса под нагрузкой.
- Выберите одно из трёх API и проведите для него тест с высокой нагрузкой. Укажите инструмент, сценарий запросов, число одновременных клиентов, длительность и интенсивность нагрузки. Тестируйте локально запущенный сервис; общий стенд нагружайте только после согласования с преподавателем.
- Подготовьте отчёт: приведите условия теста, число запросов, пропускную способность, время ответа (например, медиану и 95-й процентиль), долю ошибок, наблюдения и выводы.
- Отправьте отчёт по выбранному API преподавателю на проверку. За выполненное дополнительное задание начисляются 2 балла.
Что сдавать
Перед запросами запустите запись терминала командой script -q seminar03.log. Выполните в этом терминале команды cURL, затем завершите запись командой exit. В PowerShell используйте Start-Transcript -Path seminar03.log и Stop-Transcript. Файл должен содержать каждую команду и её вывод, включая ошибки и полный вывод характерных запросов с -v. В тот же файл добавьте сведения о запросах и ответах из Postman или Insomnia, объяснение кода HTTP 202 и обработанный CSV. Удалите токен преподавателя из снимков экрана, экспортированных данных и журнала. Сгруппируйте записи по сервисам и подпишите каждый запрос.