Версии API

Контракт /v1 только растёт: появляются новые методы, поля и значения, а то, чем уже пользуется ваша интеграция, не исчезает и не меняет смысла. Каждое изменение записано в журнале изменений.

Загружаем поисковый индекс…

Версии API

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

  • Методы, поля, параметры и заголовки не удаляются и не переименовываются.
  • Поле сохраняет тип и формат, а поле, которое приходило всегда, приходит и дальше.
  • Запрос, который работал, продолжает работать: не появляется новых обязательных полей и параметров, ограничения на вход не ужесточаются.
  • Значения type отказов и их HTTP-статусы остаются прежними.
  • Метод не начинает требовать другой scope.

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

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

Эти изменения не ломают клиента, написанного по правилам ниже, поэтому приходят в /v1 в любой момент и записываются в журнал изменений:

  • новые методы, новые необязательные параметры и поля запроса;
  • новые поля в ответах и в событиях вебхуков;
  • новые значения перечислений в ответах, например статусов заказа;
  • новые типы отказов, каждый со своим HTTP-статусом, — см. каталог ошибок;
  • новые типы событий — адрес вебхука получает только те, на которые подписан.

Устаревание

Когда у метода или поля появляется лучшая замена, они помечаются в справочнике устаревшими, а журнал изменений объявляет замену. Устаревший метод или поле работает, пока работает /v1.

Новая версия

Изменение, которое сломало бы клиентов, — удаление или переименование, смена типа, новый обязательный вход — в /v1 не делается никогда. Оно выходит как /v2 рядом с /v1, вместе с гайдом по переходу.

/v1 работает не меньше 12 месяцев после выхода /v2. Дата, когда он перестанет работать, объявляется в журнале изменений при выходе /v2, и с этого момента каждый ответ /v1 несёт заголовки Deprecation (RFC 9745) и Sunset (RFC 8594) и ссылку на объявление.

Как следить за изменениями

  • Журнал изменений перечисляет все изменения контракта по датам; его лента Atom приносит их в читалку или в рабочий чат.
  • Справочник и файл OpenAPI всегда описывают текущий контракт: перегенерируйте клиента из файла, чтобы получить новые поля.