Совместимость API backend-приложений¶
Требования применяются к опубликованным API-контрактам. Уровни обязательности
определены в корневом README.md.
BE-COMP-001. Обратно совместимое изменение¶
Уровень: MUST
Применяется к: изменению действующей версии API
Изменение должно сохранять корректность существующего запроса и семантику существующего ответа. Новое поле запроса должно быть необязательным; новое поле ответа не должно требовать изменения tolerant reader. Удаление, переименование, сужение допустимых значений или изменение смысла считается несовместимым.
Добавление значения enum в ответ считается совместимым только тогда, когда контракт заранее объявляет enum расширяемым и требует от consumer определённого поведения для неизвестного значения. В остальных случаях оно является несовместимым изменением.
Обоснование¶
Независимое развёртывание требует совместимости версий поставщика и клиента.
Проверка¶
- automated contract diff;
- consumer contract tests;
- тест старого клиента с новым поставщиком.
Исключения¶
Несовместимое изменение требует новой версии.
BE-COMP-002. Миграция несовместимой версии¶
Уровень: MUST
Применяется к: введению новой несовместимой версии API
Старая и новая версии должны сосуществовать в документированный период миграции. Должны быть определены владелец, потребители, срок прекращения, критерий отсутствия использования и способ отката.
Обоснование¶
Новая версия без периода миграции связывает развёртывание всех потребителей.
Проверка¶
- реестр потребителей и план миграции;
- метрики использования по версии;
- тест параллельной работы и отката.
Исключения¶
Экстренное отключение уязвимого контракта выполняется по OPS-INC-003.
BE-COMP-003. Проверка и публикация контракта¶
Уровень: MUST
Применяется к: каждому изменению API
Версионируемый контракт должен храниться в GitLab и проверяться CI на синтаксис, совместимость и соответствие реализации. Release не должен публиковаться при необъявленном несовместимом изменении.
Обоснование¶
Проверяемый контракт делает изменение видимым до развёртывания.
Проверка¶
- schema validation и contract tests;
- проверка compatibility gate;
- сопоставление release с commit контракта.
Исключения¶
Не допускаются для межсервисного или публичного API.