Почему API-контракту нужен менеджер, а не просто папка с файлами

Когда контракт становится важной частью банковской архитектуры, его нельзя хранить как "ну где-то лежит JSON".

JSON — это JavaScript Object Notation, текстовый формат обмена данными.

Но сам по себе файл не отвечает на вопросы:

- кто владелец API; - какая версия сейчас latest, то есть актуальная; - какие операции опубликованы; - можно ли эту версию выпускать; - не нарушена ли security policy — политика безопасности; - синхронизирован ли фронтенд; - видит ли BFF этот контракт; - что изменилось между версиями; - кто отвечает за поле в ответе.

Поэтому я сделал contract manager — менеджер контрактов.

Его задача — не просто показать manifest.

Manifest — это манифест разрешенных операций.

Задача менеджера — стать governance-слоем, то есть слоем управления правилами, публикациями и видимостью.

Что появилось:

1. Publish gate — проверка перед публикацией.

Если контракт кривой, ошибка должна стрелять не где-то в рантайме, а прямо при попытке publish.

2. Security policy admin — админка политик безопасности.

Например, query depth — глубина GraphQL-запроса. Если команда случайно публикует слишком глубокий запрос, менеджер блокирует релиз.

3. Version compare — сравнение версий.

Важно видеть, что изменилось: hash-route, OpenAPI, manifest, raw GraphQL, схемы.

4. Live deployment sync — онлайн-проверка деплоя.

Менеджер показывает:

- видит ли он BFF; - видит ли frontend; - совпадает ли версия контракта; - хватает ли операций, чтобы сценарий работал end-to-end.

5. API console — консоль вызова API.

Можно прямо из UI, то есть интерфейса пользователя, дернуть опубликованную ручку и увидеть результат.

6. Portfolio — портфель API-проектов.

Потому что в большой компании контракт не один.

Есть подразделения, команды, проекты, разные API, разные владельцы.

И тут появилась еще одна мысль:

если контрактов много, нужно видеть не только версию и hash.

Нужно видеть организационную карту:

подразделение -> команда -> проект -> API -> операция -> поле.

И желательно, чтобы описание ручки и поля жили рядом с кодом, а не в отдельной забытой вики.

Так в проекте появились annotations — аннотации, decorators/comments — декораторы и комментарии рядом с операциями.

В следующем посте расскажу, как это превращает API-каталог из "кладбища Swagger" в живой инструмент для команд.