Средний ~22 мин чтения

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

Урок 3 из 5 в курсе Проектирование REST API

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

версионирование позволяет эволюционировать API, не ломая существующих клиентов.

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

Главная идея

Версия фиксирует контракт API на определённый момент времени. Новые версии могут ломать обратную совместимость; старые поддерживаются параллельно.

Как это выглядит на практике

  1. Исходная версия: GET /api/v1/users.
  2. В v2 поле name разделяется на first_name и last_name — это breaking change.
  3. GET /api/v2/users возвращает новый формат, v1 продолжает работать.
  4. Клиенты мигрируют на v2, после чего v1 объявляется устаревшей (deprecated) и отключается.

Что происходит под капотом

  • URL-версионирование (/v1/users) — самый распространённый и простой подход.
  • Header-версионирование (Accept: application/vnd.api+json;version=2) — чище с REST-точки зрения, но сложнее тестировать.
  • Query-параметр (?version=2) — простой, но загрязняет URL.
  • Семантическое версионирование (major.minor.patch) применимо к API: major-версия меняется при breaking changes.

Типичные ошибки и заблуждения

  • Ошибка: версионирование нужно только для публичных API. Внутренние API тоже имеют клиентов, которых нужно защитить от неожиданных изменений.
  • Ошибка: добавление поля в ответ — не breaking change. Для некоторых клиентов (strict JSON parsing) — это может быть проблемой.
  • Ошибка: версии нужно менять при любом изменении. Только breaking changes требуют новой major-версии.
  • Ошибка: поддерживать много версий — нормально. Каждая дополнительная версия — это дополнительная нагрузка на поддержку.

Ключевые выводы

  • Версионируйте API с первого дня — добавить версионирование позже сложнее.
  • Breaking change = новая major-версия.
  • Объявляйте deprecation заранее и давайте клиентам время на миграцию.
  • Минимизируйте количество параллельных версий.

Термины урока

Breaking change: изменение, нарушающее совместимость с существующими клиентами.
Deprecation: объявление версии устаревшей с планом отключения.
URL versioning: включение версии в путь URL (/v1, /v2).
Backward compatibility: способность новой версии работать со старыми клиентами.

Связь с работой backend-разработчика

Закладывайте /api/v1/ в маршрутизацию с самого начала проекта. Это бесплатная страховка на случай необходимости breaking changes.

Мини-разбор реальной ситуации

Мобильное приложение использует /api/users, возвращающий поле name. Бэкенд меняет name на first_name + last_name без версионирования. Миллион установленных приложений ломается одновременно. С версионированием v1 продолжает работать, v2 доступна для новых версий приложения.

Что запомнить

  • Добавьте версионирование в API с первого дня.
  • Breaking changes требуют новой версии, не патча.
  • Deprecation требует заблаговременного уведомления клиентов.

Итог

Версионирование API — инвестиция в стабильность. Небольшие усилия при проектировании спасают от дорогостоящих инцидентов при изменении контракта.