Лабораторная работа VI: API при микросервисной архитектуре. Postman. OpenAPI/Swagger контракт, роли и проксирование

Лабораторная работа VI:  API при микросервисной архитектуре. Postman. OpenAPI/Swagger контракт, роли и проксирование

Часть 1:  API монолита и Postman 

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

Основной артефакт: экспорт Postman Collection + матрица тестов + таблица «эндпойнт → модуль монолита → сущности/таблицы»

Цель

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

Инструменты

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

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

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

1. Для каждого ресурса спроектировать операции (CRUD/поиск/действие-операция или другие).
2. Сформировать таблицу всех API, необходимых для работы разработанной информационной системы  операций:

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

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

• безопасность (safe) и идемпотентность по смыслу метода

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

1. Создать Postman Collection.
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. Для части операций добавить негативные сценарии:

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

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

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

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

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

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

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

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

Часть 2: 

 OpenAPI/Swagger контракт, роли и проксирование (основной артефакт исходный код для https://apps.thejeshgn.com/swagger-editor-next/ на основе подробного описания методов из части 1, нужно продемонстрировать свагер и рассказать про каждый из методов, а также сами контракты. Альтернативная онлайн песочница https://devtoollab.com/tools/swagger-viewer щелкнуть "paste json/yaml")

Основной артефакт: OpenAPI YAML/JSON (при работе с микросервисами) + матрица ролей + «три поверхности документации» (test/prod/admin) + контракт proxy-ручки

Цель

Сформировать навыки архитектурного контрактирования API через OpenAPI и управления доступами (аутентификация/авторизация/роли) как частью архитектуры безопасности. OpenAPI — стандарт описания HTTP API, пригодный для людей и инструментария. 

Инструменты

Любой редактор текста + валидатор/просмотрщик OpenAPI (Swagger UI/Editor допустим). В части безопасности опираемся на модель Security Scheme / Security Requirement, которая описывается в OpenAPI. 

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

Часть A: Формализация API монолита в OpenAPI

1. Описать  операции из части 1 «Postman» в формате OpenAPI 3.x.
2. Включить:

• info (название, версия),
• servers (минимум DEV и PROD),
• tags по модулям монолита,
• paths и components/schemas для основных моделей ответа/запроса.

OpenAPI позволяет описать API так, чтобы потребителю было достаточно спецификации для понимания возможностей. 

Часть B: Аутентификация и роли (RBAC) в контракте

1. Выбрать базовую схему: Bearer Token (JWT). JWT — стандартный формат передачи claims между сторонами. 
2. В OpenAPI описать security scheme для bearer auth и применить ее глобально или на отдельных операциях. Для bearer auth в OpenAPI задается type: http и scheme: bearer. 
3. Ввести минимум 3 роли (например USER, MANAGER, ADMIN) и составить матрицу доступа:

• какие операции доступны каждой роли,
• какие операции доступны без авторизации (например, health-check или публичный каталог).

Важно: на уровне безопасности API критичны корректные проверки авторизации на уровне объектов (типовой риск OWASP — broken object level authorization). 

Часть C: Три «поверхности» Swagger-документации (test / prod / admin)

Сделать один из вариантов (выберите один и обоснуйте):

Вариант 1 (рекомендуемый для учебной): три отдельных OpenAPI файла:

• openapi-test.yaml — включает тестовые/отладочные ручки (seed, mock, sandbox) и сервер DEV;
• openapi-prod.yaml — только продовый набор операций, сервер PROD;
• openapi-admin.yaml — админские ручки, отдельный базовый путь /admin/api, усиленная схема доступа (например, API key + bearer, или только bearer с ролью ADMIN).

Вариант 2: один файл, но с явным разделением:

• теги Public, User, Admin,
• разные servers,
• security requirements по операциям.

В отчете объяснить, зачем архитектор разделяет поверхности (минимизация атакующей поверхности, разные контуры эксплуатации, меньше риск «засветить» отладочные методы в проде).

Часть D: Proxy-ручка и «reverse proxy» в архитектуре монолита

1. Спроектировать минимум одну proxy-операцию внутри монолита — ручку, которая проксирует вызов во внешнюю систему (например, в платежный провайдер или внешнюю справочную систему).
2. В контракте обязателен раздел:

• входные параметры,
• какие заголовки/данные транслируются,
• таймаут/ретраи (описательно),
• как мапятся ответы и ошибки внешнего сервиса в ваши коды,
• ограничения по ролям.

Пояснить в 5–7 предложениях разницу:

• reverse proxy как инфраструктурный компонент перед приложением (маршрутизация/терминация TLS),
• proxy endpoint как прикладной контракт внутри монолита (интеграционный фасад).

Результаты

• OpenAPI спецификация(и): test/prod/admin.
• Матрица доступов «роль → эндпойнты».
• Описание proxy-ручки и маппинга ошибок.
• Короткий текст: почему выбран именно такой набор разделений.

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

• Зачем в архитектуре фиксировать API контракт в OpenAPI? 
• Чем Security Scheme отличается от Security Requirement в OpenAPI? 
• Как в OpenAPI описать Bearer Auth? 
• Почему «сломанная авторизация на уровне объектов» — один из самых опасных рисков API? 
• Что дает разделение Swagger на test/prod/admin в плане безопасности и управления изменениями?
• 
  
• 
  

Часть 3: привести диаграммы реализуемых апи методами паттернов (от банды 4 и аналогичных источников), рассказать о конкретных паттернах, как работают, для чего используются, как устроены.