Что хотят услышать интервьюеры:

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

Определение:

Версионирование API — это способ выпускать новые версии интерфейса взаимодействия так, чтобы старые клиенты продолжали работать, а новые могли использовать изменённое поведение или структуру данных. Версия отражает несовместимые изменения: например, изменение формата ответа, обязательности полей, семантики методов или набора эндпоинтов.

Пример использования:

Если в API заказа раньше ответ содержал поле price, а теперь нужно вернуть totalPrice и добавить вложенный объект delivery, это может сломать старые клиенты. Тогда вводят, например, /api/v1/orders и /api/v2/orders, чтобы постепенно перевести потребителей на новый контракт.

// Условный пример различий в ответе

// v1
{
  "id": 101,
  "price": 1200
}

// v2
{
  "id": 101,
  "totalPrice": 1200,
  "delivery": {
    "type": "courier",
    "cost": 200
  }
}

Пояснение кода:

Код здесь не требуется, потому что задача про выбор стратегии проектирования, а не про конкретную реализацию. На практике пример выглядит так: сначала клиент работает с v1, где ожидает старый формат ответа. Затем сервер вводит v2 с новым контрактом, и оба варианта доступны параллельно. Это даёт время на обновление мобильных приложений, внешних интеграций и внутренних сервисов без простоя и массовых поломок.

Ключевые моменты:

Версионирование целесообразно при несовместимых изменениях в контракте API.
Особенно полезно, если у клиентов долгий цикл обновления или их много.
Это помогает сохранить обратную совместимость и избежать резких поломок.
Версию стоит вводить, когда нельзя ограничиться расширением API без изменения старого поведения.
Часто версионируют не только URL, но и заголовки, формат данных или схему контракта.
Если изменение полностью совместимо назад, версия может быть не нужна.

В каких случаях целесообразно использовать версионирование API?