Версионирование API-контрактов: как менять интеграции без каскадных сбоев

API ломается не только при удалении поля. Несовместимость может появиться из-за нового обязательного параметра, изменения смысла статуса, более строгой валидации или другого порядка повторов. Поэтому версионирование — это управление контрактом между владельцами сервиса и всеми его потребителями, а не цифра в URL.

Сначала классифицируйте изменение

Условно безопасными обычно считаются добавление необязательного поля в запрос, добавление поля в ответ и появление нового значения, если клиент умеет обрабатывать неизвестные варианты. Но фактическая совместимость зависит от реализаций: строгий десериализатор может отвергнуть лишнее поле, а switch без ветки по умолчанию — новое значение перечисления.

Несовместимыми чаще всего являются:

• удаление или переименование поля;
• изменение типа и единицы измерения;
• новое обязательное поле;
• изменение семантики существующего статуса;
• иной формат ошибки или правила повторов;
• сокращение допустимого диапазона значений.

Каждое изменение должно иметь запись решения: что меняется, кто потребители, как определяется успешная миграция и когда старое поведение можно отключить.

Версия должна быть у контракта

Версию можно передавать в пути, заголовке или медиатипе. Важнее, чтобы она однозначно определяла схему и семантику. Если /v2 использует часть поведения /v1 без фиксации различий, команды получают две вывески над одним меняющимся контрактом.

Схемы OpenAPI, AsyncAPI или сообщения очереди следует хранить рядом с кодом и проверять в CI. Автоматическое сравнение схем помогает заметить удалённое поле, но не понимает бизнес-смысл. Например, статус accepted может остаться строкой, хотя его трактовка изменилась.

Миграция в несколько этапов

Надёжная последовательность выглядит так:

1. добавить новое поведение без отключения старого;
2. опубликовать схему, примеры и дату окончания поддержки;
3. включить метрики использования по клиентам;
4. перевести одного пилотного потребителя;
5. расширять миграцию волнами;
6. заблокировать новые подключения к старой версии;
7. отключить её только после подтверждения владельцев и периода наблюдения.

Для изменения формата события полезен паттерн expand-and-contract: сначала производитель пишет оба варианта, затем потребители переходят на новый, и только потом старое поле удаляется.

Проверяйте взглядом потребителя

Consumer-driven contract tests фиксируют минимальные ожидания конкретного клиента: нужные поля, допустимые статусы и формат ошибок. Они дополняют, а не заменяют интеграционные тесты. Отдельно проверяйте тайм-ауты, идемпотентность и поведение при повторной доставке.

Телеметрия должна отвечать на вопросы:

• какие версии реально вызываются;
• какие клиенты используют устаревшие поля;
• растёт ли доля ошибок после переключения;
• совпадают ли задержки и лимиты;
• есть ли запросы без идентификатора потребителя.

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

Чек-лист безопасного изменения

1. Инвентаризировать синхронных и асинхронных потребителей.
2. Зафиксировать текущую схему и семантику ошибок.
3. Определить совместимый переходный формат.
4. Добавить контрактные и негативные тесты.
5. Настроить метрики по версии и клиенту.
6. Назначить владельца миграции у каждой стороны.
7. Подготовить возврат без потери уже принятых операций.
8. Удалять старое поведение только после подтверждённого нулевого использования.

Практический вывод

Версионирование API работает, когда изменение имеет владельца, машинно-проверяемую схему, наблюдаемую миграцию и конечный срок поддержки. Сам /v2 не защищает от каскадного сбоя.

Общий интеграционный контур описан в статье об API-архитектуре корпоративных систем, а сценарии отказа внешнего поставщика — в руководстве по устойчивости внешних API.