Версионирование API Должно Быть Последним Средством. Окончание
Начало
Продолжение
Новая операция часто дешевле, чем новая версия
Иногда сценарий использования действительно меняется настолько, что добавление новых флагов и необязательных параметров к существующей конечной точке становится запутанным.
Вот плохой путь:
POST /orders?validateOnly=true&includeTaxEstimate=true&reserveInventory=true
Тут нет одной чистой операции, есть несколько рабочих процессов, скрывающихся за одной конечной точкой.
В этом случае лучше добавить новую операцию или ресурс. Это сохраняет стабильность старого контракта, предоставляя новому поведению чистое место. Например:
-
POST /orders остаётся простой конечной точкой «разместить заказ».-
POST /orders/quote становится операцией «скажите, сколько это будет стоить».Это обычно намного дешевле, чем создание
/v2/orders и перенос всего остального API вместе с этим.Устаревание по-настоящему
Это недостающая часть управления изменениями API. Большинство случаев устаревания — это обман. Они существуют в документации, но ничего не происходит в процессе работы. Реальный процесс устаревания должен включать:
- Пометку старого поля или конечной точки как устаревшей в описании OpenAPI;
- Сообщение об устаревании во время выполнения;
- Предоставление пользователям пути миграции;
- Измерение фактического использования перед удалением чего-либо.
Если вы используете HTTP, то сообщения во время выполнения могут быть в заголовке ответа:
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrations/orders-total>; rel="deprecation"
Теперь информация об устаревании видна в документации, видна в реальном трафике и связана с фактическим руководством по миграции.
И вот здесь телеметрия имеет значение. Если вы не знаете, какие клиенты всё ещё используют устаревшее поле или конечную точку, вы не управляете изменениями. Вы гадаете. Отслеживайте использование по ID клиента, ключу API, тенанту или имени приложения. Затем дождитесь, пока использование фактически исчезнет, прежде чем что-либо удалять.
Когда версионирование - правильное решение:
- старая и новая семантика не могут безопасно сосуществовать;
- модель ресурсов изменилась коренным образом;
- правила совместимости приводят к контракту, в котором никто не может разобраться.
А обдуманное версионирование означает выбор наименьшего возможного нарушения, которое вы можете оправдать. Иногда это новая форма конечной точки. Иногда это вариант представления. Иногда, особенно для публичных API, это прямое версионирование URL-адресов, поскольку оно явное и легко объяснимое.
Если вы используете версионирование, сочетайте его с реальным процессом устаревания (см. выше). Настоящая работа не в создании версии 2, а в том, чтобы перевести потребителей с версии 1.
Итого
Разрабатывайте контракты с учётом возможности их развития. Рассматривайте клиентов как долгосрочные интеграции, а не просто как сегодняшний код. И оставляйте версионирование для случаев, когда возможности совместимости действительно исчерпаны.
Источник: https://www.milanjovanovic.tech/blog/api-versioning-should-be-your-last-resort