📬 Пост 49. Версионирование API - зачем оно вообще нужно?

Представим, что у нас есть API: GET /api/v1/users/123 Им пользуются мобильное приложение, сайт, несколько внутренних сервисов и ещё какой-нибудь древний сервис, про который все уже забыли 😂 И тут приходит новая бизнес-задача: "Нам нужно полностью изменить структуру ответа." Вот тут и возникает проблема. Если просто поменять существующий API, старые клиенты могут получить данные в формате, который они не умеют обрабатывать. 💥 И привет, прод.

🧠 Что такое версионирование API? Это способ развивать API, не ломая потребителей, которые ещё работают со старым контрактом. Например: /api/v1/users /api/v2/users v1 продолжает работать для старых клиентов, а новые используют v2. То есть мы можем менять API постепенно, а не заставлять всех потребителей обновиться одновременно.

🔥 Зачем вообще нужна версия? Потому что API - это контракт между системами. Допустим, было: { "id": 123, "name": "Alex" } А мы решили сделать: { "user": { "id": 123, "fullName": "Alex" } } Для нового клиента всё прекрасно. А старый код ожидает: response.name и внезапно получает undefined. Если таких клиентов 50, вручную предупредить всех и одновременно обновить их может быть практически нереально.

⚠️ Но версия нужна не для любого изменения Например, добавить необязательное поле: { "id": 123, "name": "Alex", "email": "alex@mail.ru" } часто можно без создания v2. Старый клиент просто проигнорирует новое поле. А вот если мы: ❌ удаляем существующее поле ❌ меняем тип поля ❌ меняем структуру ответа ❌ меняем смысл существующего поля ❌ меняем обязательность параметра ❌ меняем поведение метода то уже может возникнуть breaking change. И тогда нужно думать о новой версии.

🔄 Как обычно версионируют API? Самые распространённые варианты: 1. В URL /api/v1/users /api/v2/users Просто и понятно. 2. Через Header Например: Accept: application/vnd.company.user.v2+json URL при этом остаётся одинаковым. 3. Через query-параметр /api/users?version=2 Тоже возможно, но используется реже.

🤔 А что происходит после появления v2? Нельзя просто создать v2 и забыть про v1. Обычно процесс такой: v1 ↓ объявляем v2 ↓ клиенты постепенно переходят ↓ v1 становится deprecated ↓ клиенты мигрировали ↓ v1 выводим из эксплуатации То есть две версии какое-то время спокойно живут параллельно.

💡 Главная мысль Версионирование API нужно не потому, что "так принято". Оно нужно, чтобы развивать контракт, не ломая существующих потребителей. Поэтому перед созданием v2 стоит задать один простой вопрос: "Мы действительно делаем breaking change или можем изменить текущий API без поломки клиентов?" Если можем - лучше не плодить версии. Если не можем - новая версия становится нормальным способом эволюции API. #api #rest #grpc #интеграции #системныйанализ