Политика версионирования

Как мы выпускаем изменения публичного API, что считаем breaking, как уведомляем и какой минимальный срок поддержки старой мажорной версии.

текущая v1.0.0 Источник правды: поле info.version в openapi.yaml. Полная история — на странице /changelog.

1. Семантическое версионирование

Версия API — это MAJOR.MINOR.PATCH по правилам SemVer 2.0.0:

MAJOR — обратно несовместимые изменения. Меняется только при breaking change. URL содержит мажорную часть: /public/v1/…, /public/v2/….
MINOR — обратно совместимые расширения (новые endpoint, новые поля в ответах, новые опциональные поля в запросах). URL не меняется.
PATCH — исправления багов без изменения контракта (правка валидации, фиксы внутреннего поведения, корректировка текстов ошибок при сохранении кода).

2. Что считаем breaking change

Breaking — это любое изменение, после которого корректный клиент v1 перестаёт работать или работает неправильно. Мажорная версия гарантирует отсутствие таких правок в рамках выпущенного контракта.

Считается breaking

Удаление endpoint или ресурса
Удаление поля из response
Переименование поля в response или endpoint
Смена типа поля (например, integer → string)
Сужение допустимого диапазона значений
Новые обязательные поля в request
Перенос обязательного поля из тела в заголовок или наоборот
Смена статус-кода для уже определённого сценария
Смена формата подписи webhook (алгоритм/кодировка)
Смена базового URL или мажорной части пути

НЕ breaking — выпускаем в minor/patch

Добавление нового endpoint
Добавление поля в response
Добавление опционального поля в request
Добавление нового значения в enum (если ваш клиент устойчив к unknown enum)
Расширение допустимого диапазона значений
Новые опциональные заголовки запроса
Новые информационные заголовки ответа
Новые коды ошибок в существующем HTTP-статусе (поле error.code)
Новые типы webhook-событий
Внутренние оптимизации, не меняющие контракт

Если вы клиент BOTIX и видите изменение, которое выглядит как breaking, но прошло в minor — это баг с нашей стороны. Напишите на info@botix.pro с темой «Breaking change в minor», приложите запрос и старое/новое поведение.

3. Срок поддержки старой мажорной версии

Старая мажорная версия живёт минимум 12 месяцев после релиза следующей. То есть если v2 выходит 1 июня 2027 года — v1 будет отключена не раньше 1 июня 2028. Реальная дата отключения объявляется в момент релиза следующей мажорной.

В период деприкации обе версии работают параллельно. Все новые endpoints и фичи появляются только в новой мажорной — v1 в этот момент в режиме maintenance (только критические security-фиксы).

4. Как мы уведомляем о deprecation

Уведомление о грядущей деприкации идёт по нескольким каналам параллельно:

HTTP-заголовок X-API-Deprecation в ответах текущей мажорной версии. Появляется в момент анонса деприкации. Содержит дату отключения в формате ISO-8601 и ссылку на migration guide: X-API-Deprecation: 2028-06-01; url="https://developers.botix.pro/migration-guide-v2". Парсите этот заголовок и поднимайте предупреждение в логах своей интеграции.
Email-рассылка подписчикам нашего changelog (подписаться можно на /changelog) — за 12 месяцев до отключения, за 6 месяцев, за 1 месяц, за 1 неделю.
Запись на странице /changelog с датой отключения и ссылкой на migration guide новой версии.
Личный email от менеджера для клиентов, у которых обнаружены активные вызовы к deprecated endpoint в логах BOTIX за последние 30 дней — за 1 месяц до отключения.

5. Стабильность вне самой версии

Несколько вещей, на которые версия API не распространяется напрямую — но мы держим их стабильными для всех клиентов на v1:

Формат Idempotency-Key: строка до 255 символов, TTL 24 часа. Не меняется без мажорного апгрейда.
Формат подписи webhook: HMAC-SHA256 от raw-тела, секрет per-подписка, hex в заголовке X-Botix-Signature. Изменение алгоритма = breaking.
Префиксы ключей: btx_live_ для production-ключей. Зарезервированы префиксы btx_test_ и btx_partner_ — могут активироваться без мажорного апгрейда.
Базовый URL https://api.botix.pro/public/v1/. TLS только 1.2+, никакого HTTP.

6. Версионирование клиентских SDK

SDK на PHP, Python и Node.js версионируются независимо от API. Мажорная версия SDK обычно совпадает с мажорной версией API (SDK 1.x.y → API v1), но не обязана — мы можем выпустить SDK 1.5.0 со сменой публичного интерфейса без апгрейда API. Schedule миграций между мажорными версиями SDK — в файле MIGRATION.md в каждом репозитории SDK.