Перейти к основному содержимому

Версионирование

Установку обновляют без простоя, а системы организации обновляются в своём темпе. Поэтому контракты, на которые они полагаются, остаются обратно совместимыми внутри major-версии:

Что считается ломающим​

Клиент, собранный под прежнюю версию, должен продолжить работать после обновления сервера. Изменение ломающее, если:

  • пропала операция, параметр или свойство, которыми клиент пользуется;
  • отправляемое клиентом значение отклоняется: новое обязательное свойство или параметр, более узкий тип, удалённое значение перечня, более жёсткое ограничение;
  • читаемое клиентом значение для него новое: более широкий тип, новое значение перечня в ответе, свойство, которого может не быть, более мягкое ограничение;
  • у событий шины и вебхуков старые сообщения остаются в топиках, поэтому в пределах major-версии событие может только получить новые необязательные свойства.

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

Что может появиться без новой версии​

  • новая операция;
  • новый необязательный параметр запроса или необязательное свойство тела;
  • новое свойство ответа или события.

Поэтому клиент:

  • игнорирует неизвестные свойства ответа и события, а не падает на них;
  • не отправляет свойств, которых нет в схеме;
  • обрабатывает неизвестный code ошибки по статусу HTTP и retryable (ошибки).

Новый вид события вебхука приходит, только если подписка его называет (events).

Версии​

  • Путь API несёт major-версию: /api/integration/v1/. Всё описанное выше действует внутри неё.
  • События несут schema_version. Сейчас у своего канала и вебхуков он равен 1.
  • SDK версионируются вместе с установкой и лежат в её комплекте поставки (SDK). Версии сред (Python, Node.js, Go, брокер Kafka) — в матрице совместимости COMPATIBILITY.md комплекта.
  • Спецификация этой версии — в справочнике и в каталоге sdk/openapi/ комплекта поставки.