Переименование поля в API изнутри кажется безобидным. Снаружи оно может положить каждый дашборд, который рассчитывал на старое имя.

Любое изменение API попадает в одну из двух категорий, и от этого зависит всё.

Если изменение ломающее, нужно поднимать версию: удаление или переименование полей, добавление обязательных параметров или фундаментальное изменение поведения эндпоинта.

Безопасные изменения можно выпускать без новой версии: добавлять необязательные поля, новые эндпоинты или просто ускорять работу.

Большая часть боли появляется из-за двух противоположных ошибок. Не версионировать вообще — и каждый релиз превращается для пользователей в лотерею. Версионировать всё подряд — и в итоге вы поддерживаете пять версий, а разработчики уже не понимают, какую использовать.

Несколько простых правил помогают держать баланс:

— Показывайте версию явно, например /v1/ в URL, как это делают Stripe и GitHub.
— Используйте семантическое версионирование, чтобы смена мажорной версии сразу означала необходимость изменений в клиентском коде.
— Если версия выводится из эксплуатации, говорите об этом прямо в ответе через заголовок Sunset и давайте 6–12 месяцев на миграцию.

Версия API — это обещание о том, что не изменится.

Нарушать его нужно редко и громко. Никогда — молча.

Какую ошибку вы встречали чаще?

👉 Java Portal