Версии и совместимость

У API одна основная версия, /v1, и она только растёт. Интеграция, написанная сегодня, продолжает работать по мере появления новых возможностей: ничто из того, на что она опирается, не переименовывается, не удаляется и не получает новый смысл.

Номер версии

У API есть номер версии, например 1.62.0. Он меняется с каждым выпуском:

минорный номер — когда что-то добавлено: операция, поле, событие;
номер патча — когда исправлено описание или текст сообщения и больше ничего не изменилось.

Версию, которую обслуживает адрес, можно узнать в любой момент:

Где	Что
`GET /openapi.json`	`info.version` спецификации
Каждое событие ленты событий и каждый вебхук	`api_version` — версия, схеме которой следует `data`

У GET /v1/health тоже есть version, но это версия выпуска Sursa, который обслуживает адрес, а не версия API.

Минорную версию вы не выбираете: каждый запрос обслуживает текущая. Благодаря правилам ниже это безопасно.

Что может меняться в /v1

Такие изменения могут прийти в любой минорной версии. Пишите интеграцию так, чтобы они её не ломали:

Новые операции.
Новые необязательные параметры и поля запросов. Запросы без них работают как раньше.
Новые поля в ответах, объектах и событиях.
Новые значения перечислений в ответах, например новый статус карточки или новый тип события.
Новые коды ошибок и новые заголовки ответов.
Ограничения, которые становятся мягче: большая максимальная длина, более широкий диапазон.
Новые формулировки текстов message в ошибках и новые формулировки описаний.

Что должен выдерживать ваш код

Пропускайте незнакомые поля. Не падайте, если в ответе больше полей, чем вы ждёте, и не используйте строгие схемы, которые их отвергают.
Принимайте незнакомые значения перечислений. Любое перечисление в ответе может расти. Считайте незнакомое значение вариантом «другое», а не ошибкой.
Пропускайте незнакомые типы событий — и в вебхуках, и в потоках.
Обрабатывайте незнакомые коды ошибок по их HTTP-статусу: см. Ошибки.
Не зависьте от порядка полей в JSON-объектах и от точного текста сообщений.

Что никогда не меняется в /v1

Путь, параметр, поле или значение перечисления никогда не переименовываются и не удаляются.
Тип поля никогда не меняется, и поле никогда не получает новый смысл, например новые единицы измерения.
Запрос, который принимается сегодня, не будет отвергнут позже.
Код статуса успешного ответа остаётся прежним.
Коды ошибок сохраняют смысл, а поле detail в ответах с ошибкой сохраняет свою форму.
Типы событий никогда не переименовываются и не удаляются, а в их data поля только добавляются.

Несовместимые изменения

Если когда-нибудь понадобится несовместимое изменение, оно выйдет новой основной версией, например /v2, рядом с /v1. /v1 продолжит работать без изменений, и обе версии будут работать параллельно.

Когда маршрут собираются вывести из работы:

Его помечают deprecated в спецификации и вносят в журнал изменений с датой, когда его отключат.
Его ответы несут заголовки Deprecation: true и Sunset: <date>.
Он продолжает работать не меньше 180 дней после объявления. Организации, ключи API которых его используют, получают письменное уведомление не позже чем за 90 дней.
После даты отключения он ещё 90 дней отвечает 410 с кодом api.gone.

Следите за заголовком Deprecation в своих журналах или мониторинге: это самый ранний сигнал, что маршрут, которым вы пользуетесь, уходит.

Как быть в курсе

Журнал изменений этого портала перечисляет все выпуски: что добавлено и что объявлено устаревшим. Прежде чем обновлять свою интеграцию, сверьте её код с записями, начиная с версии, под которую она написана.