Сообщить об ошибкеКороткий ответ
Breaking change — это изменение, после которого существующие клиенты API перестают работать корректно без изменений на своей стороне; его нужно анонсировать заранее, потому что клиентов обычно нельзя обновить мгновенно и одновременно с сервером.
Как это работает подробнее
К breaking change относятся, например, удаление или переименование поля в ответе, изменение типа поля, смена кода статуса ответа на другой смысл, изменение обязательности параметра. Такие изменения ломают код клиентов, которые полагались на старое поведение, даже если новый вариант «лучше» — для клиента важна предсказуемость контракта, а не абстрактная корректность.
Пример кода
example.txt
# Было (v1): поле содержало сумму в рублях числом
GET /api/v1/orders/42
{ "total": 1500 }
# Стало без предупреждения — breaking change:
{ "total": { "amount": 1500, "currency": "RUB" } }
# Клиенты, ожидающие число, получат ошибку парсинга.Что использовать на практике
- Практика. Перед несовместимым изменением принято: уведомить потребителей API заранее, задать срок перехода, при возможности поддержать старое и новое поведение параллельно (например, через версионирование эндпоинта) и только потом удалить старое. Для внутренних API в рамках одной команды процесс может быть проще (достаточно сообщения в общем чате и согласованного окна на обновление), но предупреждение всё равно нужно, иначе страдает соседняя команда.
Подводные камни
- Риски. Распространённая ошибка — посчитать «улучшение» неважным и выкатить его без объявления, решив, что «это же мелочь». Также ошибочно путают добавление нового необязательного поля (обычно совместимо) с изменением существующего обязательного контракта (как правило, несовместимо) — и то, и другое называют «просто доработкой API», хотя риски у них разные. Ещё одна ошибка — считать себя не обязанным думать о потребителях, если их «немного» или они «внутренние»: даже один сломанный внутренний клиент означает простой другой команды.