Версионирование API и политика устаревания¶

Версии¶

Мажорная версия API — часть URL-пути: /api/v1/…. Кодируйтесь против версии в пути — релизы платформы (v0.29, v0.30, …) никогда не меняют контракт /v1.

Неверсионированные маршруты /api/… — легаси-поверхность v0: заморожена, получает только багфиксы и больше не документируется для внешних интеграторов. Новые интеграции начинаются с /v1.

Совместимость внутри мажорной версии¶

Внутри /v1 не являются breaking и могут происходить в любом релизе:

добавление полей ответа,
добавление эндпоинтов,
добавление опциональных параметров запроса,
добавление значений enum.

Ваш клиент ОБЯЗАН быть tolerant reader: игнорировать неизвестные поля и значения enum, а не падать на них. Это требование контракта, а не рекомендация.

Breaking — и возможно только в новой мажорной версии (/v2): удаление или переименование полей, смена типов или семантики, изменение статус-кодов или идентификаторов ошибок type.

Устаревание¶

Когда что-то в /v1 объявляется устаревшим:

ответы затронутого эндпоинта несут заголовок Deprecation (RFC 9745) и дату Sunset (RFC 8594) минимум за 6 месяцев,
устаревание объявляется в changelog,
эндпоинт работает до даты sunset; само удаление происходит только со следующей мажорной версией.

Следите за этими заголовками в вашем HTTP-клиенте и воспринимайте их как раннее предупреждение, а не как отказ.

Таксономия ошибок¶

Ошибки v1 — application/problem+json со стабильным URI в type. Слаг в конце type (и расширение code, где есть) — часть контракта: ветвитесь по ним и никогда — по человекочитаемому тексту detail, который может быть переформулирован или локализован в любой момент.