Как вы проектируете API с обратной совместимостью?

Фиксирую публичный контракт и сохраняю старую семантику при добавлении возможностей. Добавление необязательного поля обычно безопаснее удаления, переименования или изменения типа существующего поля.

Проверяю не только схему, но и значения по умолчанию, порядок, коды ошибок и требования авторизации. Клиенты должны терпимо относиться к неизвестным полям, если это часть контракта. Несовместимые изменения выпускают через новую версию или переходный период с измерением использования старой. Полезны контрактные проверки и документация миграции; объявить endpoint v2 недостаточно без плана жизни v1.