Версии API: какие изменения ломают готовую интеграцию

Чтобы выпускать версии API без неожиданных поломок интеграций, проверяйте изменения контракта на действующих клиентах, а не только присваивайте новый номер. Контракт включает поля, их смысл, ошибки и поведение по умолчанию. Для несовместимого изменения нужен согласованный переход: поддерживаемые комбинации клиента и сервера, наблюдение за старой версией и проверяемое условие её отключения.

Составьте контракт, на который уже рассчитывает клиент

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

В Google AIP-180 различаются совместимость исходного кода, обмена и смысла поведения. Рекомендации имеют оговорки по транспортам и модели потребителей; это не универсальная инструкция для любого проекта. Для владельца полезен общий вывод: прежний клиент должен не просто получить ответ, а продолжить правильно выполнять согласованную задачу.

Запишите, что клиент ожидает от результата. Какие поля обязательны для его работы? Что означает отсутствие значения? Как он проходит список и обрабатывает ошибку? Не исключайте из проверки поведение, которого нет в кратком описании метода, но которое фактически использует поддерживаемый клиент. Разногласие по недокументированному ожиданию нужно разобрать, а не скрыть новым номером.

Матрица изменений до решения о выпуске

Таблица ниже — учебные случаи для проверки своего контракта, а не классификатор, который одинаково применяется всеми поставщиками. Для каждой строки важен реальный способ использования ответа. Даже формально разрешённое расширение может выявить клиент, который слишком жёстко проверяет входящие значения.

AIP-180 отдельно рассматривает обязательные поля, пагинацию, значения по умолчанию и осторожность при новых вариантах enum в ответах. У GitHub REST API есть собственная политика версий и перечни изменений; версия выбирается через предусмотренный заголовок. Эти документы полезны как примеры, но правила GitHub нельзя автоматически считать политикой вашего API.

Версия в URL и версия поведения

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

Разделите формальный выбор версии и период поддержки. Клиент должен знать, какой контракт получает, как узнаёт об изменениях и что означает переход на следующий. Не полагайтесь на неявное «всегда последняя версия» там, где потребитель не контролирует момент обновления. Если такой режим намеренно выбран, последствия и допустимые изменения должны быть понятны обеим сторонам.

Согласуйте поддерживаемые комбинации

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

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

Сохраните контрольные запросы и ожидаемые результаты на разрешённых учебных данных. Проверяйте успешные действия и ошибки. Сравнение только структуры ответа не показывает изменение смысла: поле может остаться строкой, но перестать обозначать то, на что рассчитывала интеграция. Для спорного поведения нужен зафиксированный пример и решение владельца контракта.

Переход по клиентам, а не по календарной догадке

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

Какие наблюдения нужны во время миграции

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

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

При ошибке возврат версии должен учитывать уже совершённые действия. Возвращение старого ответа не отменяет созданный заказ или изменённую запись. Для операций с последствиями согласуйте способ разбора повторов и промежуточных состояний отдельно. Здесь задача совместимости связана с рабочим процессом, а не заканчивается откатом маршрута.

Что передать владельцу API

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

Такую работу можно обсудить через разработку API-интеграций. Если меняется сама система, полезна разработка веб-приложений, а для разграничения вызовов — аудит API. Приёмка версии подтверждается сохранёнными рабочими сценариями поддерживаемых клиентов и понятным переходом остальных, а не только обновлённой документацией.