АА.Докс API lifecycle

AA.Docs API. Версии, совместимость и вывод

Интеграция должна заранее понимать, когда контракт меняется и сколько времени есть на переход. Эта страница описывает правила для REST API и машинные сигналы, которые получают клиенты.

Стабильная версия обозначается /api/v1

Минимум 180 дней на плановый переход

Deprecation, Sunset и Link в HTTP-ответах

Какие изменения совместимы

Текущая стабильная линия REST API — v1. Добавление необязательного поля, нового endpoint или нового значения, которое клиент должен уметь безопасно игнорировать, выпускается в этой линии как обратно совместимое изменение.

Удаление или переименование поля, изменение его смысла, усиление обязательности параметра либо несовместимое изменение ответа требует новой основной версии. Экспериментальный интерфейс помечается явно и не получает гарантий стабильной линии.

Как объявляется вывод

Для планового несовместимого изменения АА.Докс публикует описание миграции и сохраняет прежнюю версию минимум 180 календарных дней после объявления. Отсчёт начинается с даты, указанной в заголовке Deprecation.

Ответ устаревающего ресурса получает Deprecation по RFC 9745 в формате Structured Field Date, Sunset по RFC 8594 с HTTP-датой последнего обслуживания и Link с отношением deprecation. Активные v1-операции не получают ложные Deprecation или Sunset, но публикуют Link на действующую политику.

Deprecation: @1788134400
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://aadocs.ru/developers/api-lifecycle>; rel="deprecation"; type="text/html"

Исключения и действия клиента

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

Клиенту следует сохранять requestId, читать Link, Deprecation и Sunset, не закрепляться за недокументированными полями и проверять новую основную версию до переключения производственного трафика.

Спланировать переход без остановки процесса

Назовите используемую версию и критичные операции — команда поможет сверить контракт и последовательность проверки.

Разобрать маршрут