Жизненный цикл версий API

Что это за сервис

Реестр версий API для платформенной команды, владельцев API и команд-потребителей. Он показывает, какие версии действуют, какие объявлены устаревшими, кто ещё ими пользуется и когда старую версию можно отключить.

Без реестра статус версий разбросан по changelog, вики и чатам. Потребители узнают о несовместимых изменениях, когда у них уже что-то сломалось. Сроки отключения переносятся месяцами, потому что никто не видит, сколько клиентов ещё ходит на старые эндпоинты. На каждый релиз платформенный инженер тратит полчаса, чтобы вручную обновить документацию и разослать предупреждения.

Что он делает

Ведёт единый реестр версий. У каждой версии API есть статус (черновик, бета, действует, устарела, отключена), владелец, даты объявления об устаревании и отключения.
Показывает прогресс миграции. По данным шлюза или логов доступа видно, сколько потребителей и какая доля трафика остаётся на каждой версии.
Предупреждает потребителей заранее. Перевод версии в «Устарела» запускает рассылку зарегистрированным потребителям и напоминания перед датой отключения.
Не даёт отключить версию преждевременно. Перевод в «Отключена» возможен, только когда миграция достигла согласованного порога.
Контролирует разрастание. Для каждого API задано максимальное число одновременно действующих версий, превышение видно на дашборде.

Нюансы и особенности

Начинают с инвентаризации. Если версии нигде не учтены, их загружают из CSV или собирают из маршрутов и спецификаций OpenAPI. Пустой реестр, который обещают «заполнить потом», не заполнится.
Реестр не заменяет документацию API. Описание контрактов остаётся в OpenAPI, Scribe или портале разработчика. Приложение хранит статус, сроки и потребителей и ссылается на документацию. Если API один и потребителей два-три, хватит раздела в changelog и договорённости в чате.
Трафик — единственный честный индикатор миграции. Отметка «мы перешли» от команды-потребителя ничего не гарантирует. Долю вызовов по версиям считают фоновой задачей по логам шлюза или middleware, а дату последнего вызова показывают рядом. Внешних потребителей определяют по ключу API или токену, внутренние сервисы — по заголовку или идентификатору клиента.
Несовместимое изменение — новая версия. Деплой, помеченный как ломающий, связывают с записью версии. Если ломающее изменение уходит без новой версии, реестр должен это показать, а не молча принять.
Порог и сроки — настройки. Порог миграции (например 90%) и график напоминаний (за 90, 30 и 7 дней) хранят в конфиге или на уровне API, а не в коде. Исключения фиксируют с причиной и автором.
Черновики не шумят. Черновые и бета-версии видны в хронологии, но не участвуют в рассылках, пока их не перевели в «Действует».
Доступ по командам. Каждая команда управляет своими API, лидер платформы видит все. Ограничение действует на сервере, включая выгрузки.

Как сгенерировать через ИИ-агентов

Промпты рассчитаны на AI-агента (Claude Code, Cursor и аналоги) в Laravel-проекте с установленным Filament 4.x. Отправляйте их по одному и проверяйте результат перед следующим шагом.

1. Данные и модели

Создай модели и миграции для реестра версий API: Api (название, команда-
владелец, лимит одновременно действующих версий), ApiVersion (API, номер,
статус: черновик, бета, действует, устарела, отключена; владелец, даты
объявления устаревания и отключения, ссылка на документацию), Consumer
(название, контакт, команда), VersionUsage (версия, потребитель, дата,
число вызовов). Владелец версии обязателен. Добавь фабрики и импорт
начального реестра из CSV.

2. Реестр и карточка версии

Сгенерируй Filament-ресурсы для Api и ApiVersion. В таблице версий покажи
статус значком, даты, долю трафика за последние 7 дней и число активных
потребителей; добавь фильтры по API, команде и статусу. В карточке версии
выведи потребителей с датой последнего вызова через relation manager.

3. Переходы статусов

Добавь действия смены статуса версии. Переход в «Устарела» требует дату
отключения. Переход в «Отключена» запрещён, пока доля трафика на версии
выше порога из конфига; исключение возможно только с причиной, и оно
попадает в журнал. Подсвети API, у которых действующих версий больше
лимита.

Проверьте, что отключить версию с заметным трафиком нельзя без записи исключения.

4. Учёт вызовов и напоминания

Сделай фоновую задачу, которая раз в сутки агрегирует вызовы по версиям
из логов шлюза или таблицы запросов в VersionUsage. Добавь рассылку
потребителям при переводе версии в «Устарела» и напоминания за 90, 30
и 7 дней до отключения. Черновые и бета-версии в рассылках не участвуют.

Проверьте, что потребитель, который перестал вызывать версию, через сутки исчезает из числа активных, а дата его последнего вызова сохраняется.

5. Доступ и сводка

Настрой доступ: команда видит и меняет только свои API, лидер платформы —
все. Добавь виджеты: версии по статусам, ближайшие отключения и API
с превышением лимита версий. Добавь экспорт списка потребителей
устаревших версий.

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