Версионирование API Должно Быть Последним Средством. Начало
Про версионирование API уже была серия постов на канале. Но более важный вопрос не как это делать, а когда. Каждая команда разработчиков API в итоге приходит к одному выводу: «Просто создадим версию 2». Звучит ответственно. За исключением того, что теперь нужно поддерживать два API, два набора документации, два варианта поведения и проект миграции, которую клиенты будут откладывать как можно дольше.
Версионирование — это инструмент совместимости, а не стратегия проектирования.
Большинство изменений API не требуют новой версии. Они требуют более эффективного управления изменениями. Если вы рассматриваете каждое изменение контракта как проблему версионирования, вы в итоге плодите клоны своего API. Если же вы рассматриваете это как проблему управления изменениями, вы начинаете задавать более правильные вопросы:
- Можно ли добавить, а не заменить?
- Может ли старое и новое поведение сосуществовать некоторое время?
- Можно ли ввести новую операцию вместо изменения старой?
- Можно ли безопасно удалить что-то с помощью миграции и основываясь на данных телеметрии?
Такой подход приводит к созданию API, которые гораздо лучше выдерживают проверку временем.
Что на самом деле ломает код клиентов?
Изменения, приводящие к сбоям, обычно касаются не только URL-адреса. Это также:
- удаление или переименование поля,
- изменение значения существующих данных,
- ужесточение проверки запросов,
- изменение формата пагинации или ошибок,
- предположение, что перечисления – закрытый для изменений тип.
Это ломает клиента так же, как и удаление конечной точки:
// До
{ "total": 100 }
// После
{ "total": { "amount": 100, "currency": "USD" } }
Вы не изменили путь, не переименовали конечную точку, но всё равно сломали работу клиентов.
Поэтому вместо вопроса: «Должна ли это быть версия 2?», спросите: «Могут ли старый и новый контракты безопасно сосуществовать?»
Продолжение следует…
Источник: https://www.milanjovanovic.tech/blog/api-versioning-should-be-your-last-resort