Какие изменения REST API обратно совместимы для существующих клиентов?

Совместимые изменения (для существующих клиентов):

• новое поле в ответе;
• новый необязательный параметр запроса со значением по умолчанию, как раньше;
• новый эндпоинт или метод;
• ослабление требований к входу (принимать больше форматов).

Несовместимые:

• удаление или переименование поля;
• изменение типа ("price": "100" → 100), формата даты, единиц измерения;
• необязательное поле становится обязательным во входе;
• изменение смысла существующего значения или поведения по умолчанию;
• новое значение перечисления в ответе — ломает клиентов со строгим switch без ветки по умолчанию; об этом договариваются заранее.

Толерантный читатель — правило для клиентов: игнорировать незнакомые поля, не зависеть от порядка, обрабатывать неизвестные значения enum. Без него даже добавление поля ломает строгие десериализаторы (FAIL_ON_UNKNOWN_PROPERTIES в Jackson).

Expand–contract для ломающих изменений:

1. расширить — добавить новое поле или эндпоинт рядом со старым, заполнять оба;
2. перевести потребителей на новое, отслеживая использование старого;
3. сократить — удалить старое, когда им никто не пользуется.

Тот же приём — для схем баз данных и событий в брокере.