Любое изменение API попадает в одну из двух категорий, и от этого зависит всё.
Если изменение ломающее, нужно поднимать версию: удаление или переименование полей, добавление обязательных параметров или фундаментальное изменение поведения эндпоинта.
Безопасные изменения можно выпускать без новой версии: добавлять необязательные поля, новые эндпоинты или просто ускорять работу.
Большая часть боли появляется из-за двух противоположных ошибок. Не версионировать вообще — и каждый релиз превращается для пользователей в лотерею. Версионировать всё подряд — и в итоге вы поддерживаете пять версий, а разработчики уже не понимают, какую использовать.
Несколько простых правил помогают держать баланс:
— Показывайте версию явно, например
/v1/ в URL, как это делают Stripe и GitHub.— Используйте семантическое версионирование, чтобы смена мажорной версии сразу означала необходимость изменений в клиентском коде.
— Если версия выводится из эксплуатации, говорите об этом прямо в ответе через заголовок
Sunset и давайте 6–12 месяцев на миграцию.Версия API — это обещание о том, что не изменится.
Нарушать его нужно редко и громко. Никогда — молча.
Какую ошибку вы встречали чаще?
👉 Java Portal