Skip to Content
ДокументацияВерсионирование и устаревание

Версионирование и вывод из эксплуатации

Чтобы ваша интеграция никогда неожиданно не сломалась, мы письменно фиксируем правила, что может меняться в контракте, а что нет.

Мажорная версия указывается в URL

/api/public/v1

Мажорная версия повышается только тогда, когда обратно несовместимых изменений невозможно избежать. Версии v1 и v2 работают параллельно в течение переходного периода; от вас никогда не потребуется мигрировать за один день.

Изменения, считающиеся обратно совместимыми

Эти изменения не требуют новой мажорной версии, и ваш клиентский код должен корректно их обрабатывать:

  • Добавление нового поля в ответ.
  • Добавление нового эндпоинта или нового опционального query-параметра.
  • Добавление нового значения в перечисление (enum), например нового типа тревоги.
  • Изменение формулировки сообщения об ошибке — строковый код error.code остается неизменным, ориентируйтесь на него.
  • Изменение порядка полей в объекте JSON.
Проектируйте клиент с учетом этих правил

Игнорируйте неизвестные поля, не допускайте падения приложения при получении новых значений enum и ветвите логику по коду error.code, а не по тексту сообщения. Эти три правила защитят вашу интеграцию от большинства обновлений.

Изменения, требующие выпуска новой мажорной версии

  • Удаление или переименование поля.
  • Изменение типа поля.
  • Превращение необязательного поля в обязательное.
  • Изменение поведения по умолчанию.
  • Удаление эндпоинта.

Процесс вывода из эксплуатации (Deprecation)

Когда эндпоинт или поле планируется удалить, этот процесс не происходит незаметно — API самостоятельно предупреждает вас. Между объявлением и окончательным отключением проходит не менее 180 дней.

Анонс

Информация публикуется в истории изменений, а машиночитаемые заголовки добавляются к каждому ответу затрагиваемых эндпоинтов.

Окно миграции

Старое и новое поведение поддерживаются одновременно не менее 180 дней. Это ваше время для перехода на новый контракт.

Отключение

После даты Sunset эндпоинт начинает возвращать статус 410 Gone.

Заголовки предупреждений

Каждый запрос к устаревшему эндпоинту возвращает следующие заголовки:

ЗаголовокЗначение
DeprecationДата объявления об устаревании эндпоинта (RFC 9745).
SunsetДата окончательного отключения эндпоинта (RFC 8594).
LinkАдрес руководства по миграции с параметром rel="sunset".
WarningКраткое понятное человеку пояснение.

Пример:

HTTP/1.1 200 OK
Deprecation: Sat, 01 Aug 2026 00:00:00 GMT
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://developer.frigolive.com/ru/docs/versioning>; rel="sunset"
Warning: 299 - "This endpoint was replaced by /shipments/{shipment_id}/tracking/."

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

Самый простой способ отслеживания

Логируйте на бэкенде ответы, содержащие заголовок Sunset, и настройте оповещение:

response = requests.get(url, headers=headers, timeout=20)
sunset = response.headers.get("Sunset")
if sunset:
    logger.warning("Frigolive endpoint will be retired: %s -> %s", url, sunset)

Вы также можете отслеживать изменения через Atom-ленту.

История изменений

Каждое изменение контракта публикуется в хронологическом порядке на странице История изменений.

SDK и OpenAPI