Лабораторная работа 5: API монолита и Postman

Лабораторная работа 5: API монолита и Postman (основной артефакт json отправляемого и получаемого для каждого запроса, также описать назначение каждого поля json, его тип данных и назначение, для описания json и апи использовать соотвествующие диаграммы)

Дисциплина: Проектирование архитектуры информационных систем
Продолжительность: 2 пары (3 акад. часа)
Форма проведения: индивидуальная работа + мини-защита (3-5 минут)
Основной артефакт: экспорт Postman Collection + матрица тестов + таблица «эндпойнт → модуль монолита → сущности/таблицы»

Цель

Научить студента переходить от архитектуры монолита (ЛР2) к внешнему контракту взаимодействия: REST API, проверяемому через Postman. При этом акцент - на архитектурном качестве: правильное разбиение ресурсов, корректные методы, коды ответов, идемпотентность и устойчивость к повторным запросам. Семантика HTTP и свойства методов (safe/idempotent) задаются стандартом HTTP. 

Исходные данные (вход)

Артефакты ЛР1-ЛР2:

• требования (ФТ/НФТ), сценарии качества;
• подсистемы/модули монолита;
• ERD/сущности и связи;
• диаграммы развертывания и компонентов монолита.

Инструменты

Postman Desktop (без обязательного доступа к интернету). Для работы с переменными и тестами используются стандартные механизмы Postman: переменные и Postman Sandbox (pm.test и т.п.). 

Структура работы

Часть A: Каталог API-ресурсов монолита (архитектурный уровень)

1. Выделить минимум 4-6 ключевых ресурсов из доменной модели (например: Пользователь, Заказ, Платеж, Запись, Товар, Клиент и т.п.).
2. Для каждого ресурса спроектировать минимум 3 операции (CRUD/поиск/действие-операция).
3. Сформировать таблицу «операция» (минимум 15 операций):

• ресурс и URL (например /api/v1/orders/{id}),
• HTTP-метод (GET/POST/PUT/PATCH/DELETE),
• назначение операции,
• основной владелец модуля (из ЛР2),
• какие таблицы/сущности затрагиваются (из ERD),
• коды ответов (200/201/204/400/401/403/404/409/422/500 - по смыслу).

Отдельно отметить для каждой операции:

• безопасность (safe) и идемпотентность по смыслу метода (GET должен быть safe; PUT/DELETE - идемпотентны по intended effect). 

Часть B: Коллекция Postman как «исполняемый контракт»

1. Создать Postman Collection ИС_<Тема>_Monolith_API.
2. Создать минимум 2 окружения (environments): DEV и TEST (опционально PROD как шаблон).
3. В окружениях завести переменные: baseUrl, token, adminToken (если есть), userId, entityId и т.п. Переменные позволяют переиспользовать значения в запросах и сценариях. 
4. Для каждого эндпойнта настроить:

• полный URL через {{baseUrl}},
• параметры path/query,
• тело запроса (JSON) и пример ответа (если есть возможность сохранить пример).

Часть C: Тесты в Postman (проверка качества контракта)

1. Для каждого запроса добавить минимум 2 проверки в Tests:

• статус-код ожидаемый,
• наличие обязательных полей в ответе/формат.
  Postman поддерживает тесты через pm.test и pm.expect. 

1. Для минимум 5 операций добавить негативные сценарии:

• без токена → ожидается 401,
• недостаточно прав → 403,
• несуществующий id → 404,
• бизнес-конфликт → 409 (например, повторная оплата),
• ошибка валидации → 400/422 (по вашей договоренности).

Часть D: Архитектурный анализ надежности API

Коротко (½ страницы) описать:

• какие операции сильно рискуют дублями при повторах (например, создание заказа, платеж),
• где нужно применять идемпотентность на уровне бизнес-операции (например, заголовок Idempotency-Key для POST-команд),
• какие операции должны быть строго транзакционны (подводка к ACID в монолите).

Результаты (выход)

• Postman Collection (экспорт JSON).
• 2 environment-файла (DEV/TEST).
• Таблица операций (15+).
• Мини-анализ: idempotency/риски дублей/ошибки.

Контрольные вопросы

• Что означает идемпотентность HTTP-метода и почему она важна при ретраях? 
• Чем PUT отличается от PATCH с точки зрения контракта и повторяемости?
• Какую роль играют переменные окружения в Postman? 
• Как писать проверки в Postman через pm.test и зачем это архитектору? 
• Какие НФТ (производительность/безопасность/наблюдаемость) должны отражаться в API-контракте хотя бы косвенно?

Критерии оценивания (пример)

Полнота API-каталога (25%), корректность REST/методов/кодов (25%), качество Postman-коллекции и переменных (20%), покрытие тестами и негативными кейсами (20%), архитектурный анализ идемпотентности/рисков (10%).