Сообщить об ошибкеКороткий ответ
Обратную совместимость обеспечивают, добавляя новые поля как необязательные с дефолтным поведением при их отсутствии, не удаляя и не переименовывая существующие поля без периода параллельной поддержки обеих версий.
Как это работает подробнее
Совместимые изменения — добавление нового необязательного поля, ослабление валидации; несовместимые — удаление поля, которое кто-то читает, изменение смысла существующего поля без изменения его имени.
Пример кода
payload.json
// v1 ответ
{"id": 1, "total": 1500}
// совместимое изменение — добавили поле, не трогая старое
{"id": 1, "total": 1500, "total_formatted": "1 500 ₽"}Что использовать на практике
- Практика. При необходимости удалить/изменить поле вводят период deprecation — поле помечается устаревшим, но продолжает поддерживаться параллельно с новым, пока потребители не перейдут; миграцию отслеживают по метрикам использования старого поля.
Подводные камни
- Риск. Считать переименование поля «мелким» изменением, не требующим версионирования; удалять поле, не проверив по логам/метрикам реальных потребителей.