Версионирование и обратная совместимость
↑ 5.1 Проектирование REST API · ← Предыдущая · → Следующая
Зачем это на собесе
Как менять API, у которого уже есть клиенты, не ломая их.
Объяснение
Ключ — эволюция без поломки: добавляйте, не меняйте. Версия нужна только при неизбежном ломающем изменении.
| Изменение | Совместимо? |
|---|---|
| Новое необязательное поле в ответе | да (клиент должен игнорировать неизвестные поля) |
| Новый необязательный параметр запроса | да |
| Новый endpoint | да |
| Новое значение enum | опасно, если клиент строго валидирует |
| Удаление/переименование поля | нет |
| Изменение типа или семантики поля | нет |
| Ужесточение валидации | нет |
Стратегии: версия в URL (/v2/...), в заголовке или media type, либо «версия по дате» (Stripe: Stripe-Version: 2024-06-20).
Процесс депрекации: объявить → заголовки Deprecation, Sunset → мониторинг использования старой версии → уведомление клиентов → отключение.
Принцип Postel и толерантные клиенты
Клиент игнорирует неизвестные поля, сервер принимает разумное подмножество — это делает расширение безопасным.
Нюансы и подводные камни
- Версионирование всего API ради одного поля создаёт лишнюю поддержку; рассмотрите расширение.
- Поддерживайте не более 2–3 версий одновременно.
- Контрактные тесты (Pact) ловят поломки до релиза.
- В событиях и очередях версионирование схем (Schema Registry) — отдельная задача.
Практика
- Составьте матрицу совместимых и ломающих изменений вашего API.
- Введите заголовки
DeprecationиSunsetдля устаревающего endpoint. - Добавьте метрику использования версий API.
Вопросы с ответами
Что считается ломающим изменением?
Удаление/переименование полей, смена типов, семантики, ужесточение валидации.
Как выводить версию из эксплуатации?
Deprecation-заголовки, мониторинг использования, коммуникация с клиентами, дата отключения.