Сообщить об ошибкеКороткий ответ
Новое поле добавляется как опциональное с безопасным значением по умолчанию на уровне ответа API, а по-настоящему обязательным для бизнес-логики оно может стать только после того, как все активные клиенты обновятся и начнут его учитывать, что обычно контролируется версионированием или метриками использования.
Как это работает подробнее
Добавление нового поля в JSON-ответ само по себе обычно обратно совместимо: старые клиенты, которые не знают об этом поле, просто его игнорируют. Проблема возникает, если поле должно быть обязательным сразу (например, без него бизнес-логика на клиенте некорректна) — тогда нужен переходный период, пока не обновятся все клиенты.
Пример кода
example.txt
# Переходный период: поле добавлено опциональным со значением по умолчанию
GET /api/v2/orders/42
{
"id": 42,
"total": 1500,
"loyalty_points": 0 // новое поле, по умолчанию 0 для старых клиентов,
// пока они не обновлены и не учитывают его в UI
}Что использовать на практике
- Практика. Стоит выкатить поле как опциональное, заложить разумное значение по умолчанию для старых клиентов, и отслеживать через метрики или заголовок версии приложения, какая доля трафика уже обновилась. Если клиент не обновляется долго (мобильные приложения могут жить в сторах годами), может потребоваться версионирование эндпоинта (v2) или принудительное уведомление об обновлении в приложении, чтобы не поддерживать совместимость бесконечно. Решение о сроке поддержки старого поведения стоит согласовывать вместе с владельцем продукта, а не определять его в одиночку.
Подводные камни
- Риски. Частая ошибка — предположить, что раз поле «не критично», можно не думать о совместимости, а потом обнаружить, что старая версия мобильного приложения падает при парсинге нового поля неожиданного типа. Другая ошибка — игнорировать долгий хвост необновлённых клиентов и считать, что все перейдут на новую версию API сразу после релиза, хотя на практике переход может растянуться на месяцы. Также ошибочно менять смысл уже существующего поля вместо добавления нового, рассчитывая, что клиенты «не заметят».