При эволюции API часто приходится менять названия полей, типы или удалять устаревшие атрибуты. Прямое изменение сломает всех существующих клиентов. Необходимо поддерживать несколько версий одновременно, позволяя клиенту выбирать версию.
Способы версионирования:
Через URL (
/v1/customers, /v2/customers) – самый простой и наглядный. Минус: меняется endpoint, клиентам нужно обновлять код вызовов.Через параметр запроса (
?version=2) – менее явно, может кэшироваться некорректно.Через заголовок Accept – стандартный способ для REST, основанный на медиатипах. Клиент указывает желаемую версию в заголовке, например:
Accept: application/vnd.myapi.v2+json. Сервер, прочитав заголовок, сериализует ответ в соответствующем формате.Почему B – правильный ответ:
Использование
Accept соответствует принципам REST (content negotiation).Не засоряет URL, сохраняет единый endpoint.
Позволяет гибко комбинировать версию и формат (JSON, XML).
Сравнение с другими вариантами:
A (параметр
?version) – тоже возможен, но менее чистый с точки зрения REST.C (разные URL) – классический подход, но вопрос явно описывает заголовок как способ указать версию.
D (тело запроса) – нестандартно, требует разбора тела до того, как будет понята версия (курица-яйцо).
Реальный пример:
GitHub API версионирует через заголовок
Accept: application/vnd.github.v3+json. Это позволяет им добавлять новые поля, не ломая старых клиентов.Что должен зафиксировать аналитик:
В требованиях указать, что API поддерживает версионирование через заголовок
Accept.Документировать возможные значения (v1, v2, latest).
Определить политику депрекации старых версий.
Вывод: Версионирование через заголовок
Accept – гибкий и REST-совместимый способ, особенно когда URL должен оставаться стабильным.