ADR-0028: API Versioning И Client Generation
Статус
Принято.
Контекст
User, admin и partner frontends должны безопасно развиваться вместе с backend services. Handwritten HTTP clients и неявные breaking changes быстро приводят к расхождению контрактов.
Решение
HTTP API версионируется через route /api/vN/.... Каждый сервис публикует OpenAPI artifact. Frontend использует generated clients и тонкие adapters для UI state.
Последствия
- Breaking changes требуют новой версии или documented migration window.
- CI проверяет OpenAPI compatibility.
- Generated clients создаются только из OpenAPI artifacts и не редактируются вручную.
- Client adapters отвечают за UI state/query keys, но не меняют shape API contract.
- Новые endpoints требуют API doc и permission catalog entry, если endpoint защищен.
- Frontend wrappers не дублируют shape контрактов вручную.
Обратные ссылки
Автоссылки: где используется этот документ.