Версионирование позволяет развивать API и давать клиентам время на обновление. Пока одни переходят на новый контракт, другие продолжают работать со старым.
Под клиентом здесь понимается всё, что вызывает твой API: фронтенд, мобильное приложение, другой сервис или интеграция партнёра. У каждого свой график обновлений. Backend ты можешь выкатить сегодня, а приложение на телефоне пользователя останется прежним ещё несколько месяцев.
Например, раньше API возвращал адрес одной строкой: "address": "Москва, Ленина, 10". Теперь ты хочешь передавать город, улицу и дом отдельными полями внутри объекта. Старое приложение ожидает строку и не умеет обрабатывать новую структуру. Версионирование позволяет сохранить прежний ответ в v1, а новый формат выпустить в v2.
Новая версия нужна, когда изменение нарушает совместимость с поддерживаемыми клиентами. Если переименовал поле, изменил его тип или сделал необязательный параметр обязательным, проверь, смогут ли прежние клиенты продолжить работу.
При этом совместимость затрагивает и смысл данных. Поле price может остаться числом, но переход с рублей на копейки изменит результат расчётов у клиента. Формально JSON прежний, а поведение уже другое.
Добавление необязательного параметра обычно совместимо, если без него сохраняется прежнее поведение. Новое поле ответа тоже часто можно добавить в текущую версию, но нужно проверить, умеют ли клиенты игнорировать неизвестные поля.
Клиент может выбирать версию несколькими способами:
В пути:
/api/v2/orders. Версия сразу видна в URL и логах.В параметре запроса:
/api/orders?api-version=2.В отдельном заголовке:
Api-Version: 2.В media type:
Accept: application/vnd.example.v2+json.
Универсального варианта нет, путь удобно читать и проверять вручную. Заголовки позволяют сохранить URL, но их нужно учитывать в диагностике и настройках кэширования. Выбор зависит от клиентов и инфраструктуры проекта.
Само появление /v2 ещё не завершает переход. Ты запускаешь новый контракт рядом со старым, описываешь изменения и даёшь потребителям срок на миграцию. Затем смотришь, кто продолжает обращаться к v1, и связываешься с владельцами этих интеграций.
Удалять старую версию стоит только после проверки потребителей и согласованного срока поддержки. За день в логах может не оказаться ни одного запроса, хотя раз в месяц через этот API выгружается отчёт. Поэтому короткого периода тишины недостаточно.
Поддержку нескольких версий тоже приходится оплачивать временем команды: проверять их тестами, исправлять ошибки, обновлять документацию. Поэтому сроки и условия отключения лучше определить заранее.
Ещё полезно различать версию API и версию сборки сервиса. Ты можешь десятки раз обновить backend, сохранив контракт v1. Рефакторинг, оптимизация запросов и внутренние изменения сами по себе не требуют нового номера API.
Для проверки совместимости можно сравнивать OpenAPI с опубликованной спецификацией в CI. Такое сравнение помогает находить изменения полей и операций. Изменение смысла price при этом может остаться незамеченным, поэтому нужны и тесты сценариев клиентов.
Многие компании не имеют стандартов версионирования API. Когда я работал в Rostic's разработчики понимали, что такое версионирование, но единого подхода не было. Пришлось его разрабатывать, чтобы новые версии появлялись только в нужном случае. Если ты сам отвечаешь за свои сервисы, то старайся минимизировать количество изменений контрактов публичных методов, а особенно ломающих изменений. Делай новую версию, для ломающего изменения. Лучше довести до потребителей, что версия поменялась, чем потом ловить баги на проде из-за несовместимого с клиентом изменения в текущей версии.
Если хочешь подготовиться к техническим собеседованиям и записаться на менторство, напиши мне, обсудим твой опыт и план поиска работы.
#техничка #backend