Стратегии версионирования API: URL, заголовки и параметры запроса

Почему версионирование API важно

API документацию — это контракт между поставщиком сервиса и потребителями. По мере развития API ломающие изменения неизбежны: новые поля, переименованные эндпоинты, измененные структуры ответов, устаревшая функциональность. Без стратегии версионирования каждое изменение рискует сломать существующие интеграции. Грамотный подход к версионированию обеспечивает эволюцию при сохранении стабильности.

Три основных подхода к версионированию

1. Версионирование через URL-путь

Наиболее распространенный и наглядный подход, при котором номер версии встраивается непосредственно в путь URL.

GET /api/v1/users/123
GET /api/v2/users/123
GET /api/v3/users/123

Преимущества:

• Немедленно видно и самодокументируемо
• Легко маршрутизировать на уровне балансировщика или API-шлюза
• Просто реализовать в любом веб-фреймворке
• Кешируется CDN и прокси без специальной настройки
• Четкое разделение в логах, метриках и дашбордах мониторинг сайтов

Недостатки:

• Засоряет пространство имен URL — версия не является частью идентификатора ресурса
• Клиенты должны обновлять URL при переходе, даже если изменился только один эндпоинт
• Может привести к дублированию кода между директориями версий без тщательного управления
• Мажорные версии могут ощущаться избыточными для незначительных ломающих изменений

2. Версионирование через заголовки

Версия указывается в пользовательском проверку HTTP-заголовков, сохраняя URL чистыми и ориентированными на ресурсы.

GET /api/users/123
Accept: application/vnd.myapi.v2+json

# Или через пользовательский заголовок:
GET /api/users/123
X-API-Version: 2

Преимущества:

• URL остаются чистыми и представляют идентификаторы ресурсов
• Ближе к принципам REST — URI идентифицируют ресурсы, а не версии
• Позволяет детальное версионирование на уровне ресурса
• Согласование контента через Accept — устоявшийся HTTP-паттерн

Недостатки:

• Не видно в URL браузера или простых curl-командах без явных заголовков
• Сложнее тестировать вручную и делиться ссылками на API
• Некоторые CDN и прокси могут некорректно передавать пользовательские заголовки
• Требует более сложной логики маршрутизации в API-шлюзе
• Документация должна четко объяснять требования к заголовкам

3. Версионирование через параметр запроса

Версия передается как параметр запроса — промежуточный вариант между URL и заголовками.

GET /api/users/123?version=2
GET /api/users/123?v=2

Преимущества:

• Легко добавить к существующим API без реструктуризации URL
• Необязательный параметр с значением по умолчанию делает внедрение постепенным
• Виден в URL для простой отладки и обмена ссылками
• Просто реализовать — достаточно прочитать параметр запроса

Недостатки:

• Может мешать кешированию, если CDN не включает параметры запроса в ключи кеша
• Смешивание параметров ресурса с мета-параметрами загромождает строку запроса
• Менее заметно, чем версионирование через URL-путь
• Не идиоматично для RESTful API

Сравнительная матрица

Лучшие практики обратной совместимости

Независимо от метода версионирования, поддержание обратной совместимости снижает частоту ломающих обновлений:

Неломающие изменения (версия не меняется)

• Добавление новых необязательных полей в тело запроса или ответа
• Добавление новых эндпоинтов или ресурсов
• Добавление новых необязательных параметров запроса
• Добавление новых значений enum (если клиенты корректно обрабатывают неизвестные значения)
• Увеличение лимитов запросов или квот

Ломающие изменения (требуют смены версии)

• Удаление или переименование полей в теле ответа
• Изменение типов данных полей (строка на число, массив на объект)
• Удаление эндпоинтов или HTTP-методов
• Превращение ранее необязательных полей в обязательные
• Изменение механизмов аутентификации или авторизации
• Изменение формата ответов об ошибках

Процесс депрекации

Четкий процесс депрекации уважает потребителей API и дает им время на миграцию:

1. Объявление депрекации: добавьте заголовок Sunset к ответам устаревшей версии с планируемой датой удаления. Опубликуйте уведомление в чейнджлоге API и проверку портов разработчика.
2. Руководства по миграции: документируйте каждое изменение между версиями с конкретными примерами до/после. Предоставьте примеры кода для типичных сценариев миграции.
3. Мониторинг использования: отслеживайте количество запросов по версиям. По возможности связывайтесь с потребителями, все еще использующими устаревшие версии.
4. Период ожидания: поддерживайте устаревшие версии минимум 6-12 месяцев после объявления депрекации. Для корпоративных API — 12-24 месяца.
5. Отключение: возвращайте ответ 410 Gone после даты заката с телом, указывающим на руководство по миграции и новую версию.

# Заголовки депрекации в ответе API
HTTP/1.1 200 OK
Sunset: Sat, 01 Mar 2026 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/docs/migration-v2-to-v3>; rel="deprecation"
X-API-Version: 2

Паттерн реализации

// Обработка версии на уровне маршрутизатора (пример на PHP)
$version = getRequestedApiVersion($request);

switch ($version) {
    case 3:
        return handleV3($request);
    case 2:
        $response = handleV2($request);
        $response->addHeader('Sunset', '2026-03-01');
        $response->addHeader('Deprecation', 'true');
        return $response;
    default:
        return errorResponse(410, 'API v1 has been retired');
}

Выбор стратегии

Для большинства команд версионирование через URL-путь — прагматичный выбор. Оно простое, наглядное, хорошо поддерживается инфраструктурными инструментами и понятно каждому разработчику. Резервируйте версионирование через заголовки для API, где чистота URL — строгое требование или необходимо версионирование по ресурсам. Избегайте параметров запроса для новых API — это дает мало преимуществ перед URL-путем при усложнении кеширования.

Заключение

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