Что не меняется в /v1 никогда
- Методы, поля, параметры и заголовки не удаляются и не переименовываются.
- Поле сохраняет тип и формат, а поле, которое приходило всегда, приходит и дальше.
- Запрос, который работал, продолжает работать: не появляется новых обязательных полей и параметров, ограничения на вход не ужесточаются.
- Значения
typeотказов и их HTTP-статусы остаются прежними. - Метод не начинает требовать другой scope.
Единственное исключение — изменение, которое закрывает уязвимость или нужно по закону: оно может выйти раньше, и журнал изменений объявляет его как можно раньше.
Что может появиться без предупреждения
Эти изменения не ломают клиента, написанного по правилам ниже, поэтому приходят в /v1 в любой момент и записываются в журнал изменений:
- новые методы, новые необязательные параметры и поля запроса;
- новые поля в ответах и в событиях вебхуков;
- новые значения перечислений в ответах, например статусов заказа;
- новые типы отказов, каждый со своим HTTP-статусом, — см. каталог ошибок;
- новые типы событий — адрес вебхука получает только те, на которые подписан.
Устаревание
Когда у метода или поля появляется лучшая замена, они помечаются в справочнике устаревшими, а журнал изменений объявляет замену. Устаревший метод или поле работает, пока работает /v1.
Новая версия
Изменение, которое сломало бы клиентов, — удаление или переименование, смена типа, новый обязательный вход — в /v1 не делается никогда. Оно выходит как /v2 рядом с /v1, вместе с гайдом по переходу.
/v1 работает не меньше 12 месяцев после выхода /v2. Дата, когда он перестанет работать, объявляется в журнале изменений при выходе /v2, и с этого момента каждый ответ /v1 несёт заголовки Deprecation (RFC 9745) и Sunset (RFC 8594) и ссылку на объявление.
Как следить за изменениями
- Журнал изменений перечисляет все изменения контракта по датам; его лента Atom приносит их в читалку или в рабочий чат.
- Справочник и файл OpenAPI всегда описывают текущий контракт: перегенерируйте клиента из файла, чтобы получить новые поля.