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

Как версионируется API и какое уведомление вы получаете, прежде чем что-либо будет выведено из эксплуатации.

Одна версия, в пути

Все публичные эндпоинты живут под /v1. Нет ни подверсий, ни версий по датам, ни заголовка версии — /v1 и есть вся схема версионирования.

Это осознанный выбор, а не незавершённая работа. Модель с закреплением по дате (когда каждая интеграция заморожена на состоянии API определённого дня) даёт интеграторам стабильность ценой того, что провайдер вечно поддерживает все исторические формы. Мы выбрали более простой контракт: /v1 развивается аддитивно, а всё, что нельзя добавить, выводится из эксплуатации через опубликованный срок уведомления.

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

Только аддитивные изменения. Постройте клиент так, чтобы они его не ломали:

• Новые эндпоинты, новые необязательные query-параметры, новые необязательные поля запроса.
• Новые поля в объекте ответа. Игнорируйте незнакомые поля, а не отклоняйте полезную нагрузку целиком.
• Новые значения перечислений, включая новые коды error. Незнакомый error обрабатывайте откатом на HTTP-статус: списки кодов у конкретных эндпоинтов в справочнике — это выборка того, что вы вероятнее всего увидите, а не замкнутое объединение. См. Ошибки.

Что не меняется без уведомления, описанного ниже

Удаление эндпоинта, удаление или переименование поля ответа, сужение принимаемого ввода, изменение смысла существующего поля.

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

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

HTTP/1.1 200 OK
Deprecation: @1788652800
Sunset: Sat, 06 Mar 2027 00:00:00 GMT
Link: <https://docs.foxguide.io/ru/docs/changelog/>; rel="deprecation"

Значения этих двух заголовков записаны в РАЗНЫХ синтаксисах и невзаимозаменяемы. На этом спотыкается почти каждый клиент, который их разбирает:

Оба примера выше описывают одну и ту же пару моментов: объявлено устаревшим 2026-09-06, вывод 2027-03-06. Deprecation разбирайте, отбросив ведущий @ и прочитав целое число; Sunset — парсером HTTP-date. Клиент, скормивший один из них парсеру другого, получит пустую дату и молча потеряет уведомление.

Link необязателен и, если присутствует, указывает на руководство по миграции для этой операции.

Что на самом деле обещает каждый заголовок

• Deprecation — это подсказка, а не разрешение. RFC 9745 прямо говорит, что объявление устаревшим не меняет того, что ресурс делает сейчас. Эндпоинт ведёт себя ровно как прежде; можно продолжать вызывать его без изменений, пока он действительно не исчезнет.
• Sunset — дата, когда он предположительно перестанет отвечать. Когда присутствуют оба заголовка, Sunset никогда не раньше Deprecation.

Срок: 6 месяцев

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

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

Заголовков необходимо, но категорически недостаточно

Заголовок, который никто не читает, — не уведомление. Вывод из эксплуатации сопровождается:

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

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

← Вся документация