---
title: Жизненный цикл версий API
description: "Реестр версий API на Laravel + Filament: статусы от черновика до вывода из эксплуатации, потребители, прогресс миграции и сроки отключения."
---

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

Реестр версий 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. Данные и модели

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

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

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

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

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

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

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

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

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

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

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

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

## Похожие сценарии

- [Мониторинг API и SLA эндпоинтов](https://wpcraft.ru/kb/stacks/filament/use-cases/engineering/api-monitoring-dashboard.md) — текущее состояние эндпоинтов каждой версии.
- [Журнал деплоев по окружениям](https://wpcraft.ru/kb/stacks/filament/use-cases/engineering/deployment-tracker.md) — связь ломающих изменений с конкретными релизами.
- [Карта зависимостей сервисов](https://wpcraft.ru/kb/stacks/filament/use-cases/engineering/service-dependency-map.md) — какие внутренние сервисы являются потребителями API.

## Материалы и источники

- [Refine: API Version Lifecycle](https://refine.dev/use-cases/engineering/api-version-lifecycle/)
- [Filament 4.x: ресурсы](https://filamentphp.com/docs/4.x/resources/overview)
- [Filament 4.x: связи и relation managers](https://filamentphp.com/docs/4.x/resources/managing-relationships)
- [Filament 4.x: импорт](https://filamentphp.com/docs/4.x/actions/import)
- [Filament 4.x: экспорт](https://filamentphp.com/docs/4.x/actions/export)