Компания меняет оформление заказа. Новый клиент понимает дополнительные статусы, а мобильное приложение, установленное год назад, — нет. Партнёра попросили обновить интеграцию, но у него собственные планы релизов. Выключить старый контракт прямо сейчас означает сломать работающий продукт.
API Versioning позволяет старому и новому способу взаимодействия существовать одновременно. Это полезная независимость во времени. Однако за неё придётся платить тестированием, исправлениями, поддержкой и иногда отдельной бизнес-логикой.
Версия нужна не каждому новому полю
Прежде чем вводить v2, стоит понять, меняется ли контракт несовместимым образом. Дополнительное необязательное поле ответа часто может оказаться безопасным для потребителя, который игнорирует незнакомые поля. Но не все клиенты это умеют: некоторые строго проверяют ответ и ломаются на любой неожиданности.
Переименование существующего поля, изменение смысла статуса, появление нового обязательного параметра или другой способ обработки ошибок уже значительно рискованнее. Здесь важно оценивать не красоту схемы, а то, как конкретные потребители используют API.
Иногда новое поведение лучше вводить отдельно, сохраняя прежнее. Иногда необходимо явно выпустить новую версию. Но выбор должен исходить из несовместимости, а не из желания обновить номер.
Что означает поддерживать две версии
Публичный контракт — это не только URL с v1 или параметр версии. К нему относятся формат данных, правила ошибок, ограничения, документация, тесты совместимости и гарантии безопасности. Если одновременно работают несколько версий, всё важное может потребоваться проверять для каждой.
Не обязательно дублировать весь сервер. Разные версии могут обращаться к одной бизнес-модели через адаптеры, пока различия остаются на границе API. Но некоторые изменения — например, другая трактовка возвратов — затрагивают именно бизнес-правила. Скрывать это под «ещё одним контроллером» не получится.
Версионирование снижает необходимость общего дня переключения. Но если в компании нет плана завершения миграции, временный мост быстро становится постоянным legacy.
Дату отключения нужно обещать осторожно
Хорошая политика должна отвечать на вопросы: кого затрагивает новая версия, что именно требуется изменить, сколько продлится поддержка старой и как узнать, что переход выполнен. Для внешних партнёров это фактически часть коммерческих отношений.
Я бы сначала наладил учёт реальных потребителей версий. Иначе легко месяцами готовить отключение, не зная, какое приложение ещё вызывает старый endpoint. Метрики можно собирать по версии, клиентскому идентификатору и операциям, не превращая журнал в хранилище секретов и персональных данных.
Важно отдельно определить, что произойдёт с критическими исправлениями: если в старом контракте обнаружили проблему безопасности, компания не всегда может просто дождаться окончания срока поддержки. Иногда нужны обратная совместимость исправления или ускоренная миграция.
Что я бы проверил до v2
Попросил бы показать конкретное несовместимое изменение и список систем, которые от него зависят. Затем обсудил бы три варианта: совместимое расширение прежнего контракта, переходный адаптер или новая версия с заранее оговорённым сроком жизни.
Для независимых потребителей полезны контрактные проверки. Они помогают обнаружить несовместимость до релиза, но не делают миграцию за партнёра. О принципах версионирования и обратной совместимости также говорится в Azure Architecture Center.
Версия API — не улучшение само по себе. Это договор о том, сколько времени клиенты могут оставаться в прошлом, пока продукт движется дальше. Цена договора должна быть понятна обеим сторонам.