🔢 Версионирование API

Я помогаю Golang, Java и C# разработчикам находить работу и проходить собеседования: резюме и отклики, которые доходят до HR, спокойный собес и торг по офферу. Разбираю механику найма изнутри, я провёл более 100 собеседований. Без воды, только чек-листы и готовые фразы.

версионированиеapiopenapi

Версионирование позволяет развивать 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

Читайте так же