Версионирование и устаревание

Где живёт версия

Версия — это сегмент пути, и это единственное место, где она появляется:

https://api.zelnum.com/api/v1

Живая версия одна. В документе OpenAPI она обозначена как 1.0.0; вы адресуете сегмент пути v1. Тела ответов намеренно не повторяют версию, поэтому нет второго поля, которое нужно синхронизировать.

Как классифицируются изменения

Класс	Примеры	Влияние на вас
Аддитивные	Новый эндпоинт, новое необязательное поле запроса, новое поле ответа, новый продукт в каталоге	Нет. Версия не повышается, действий не требуется.
Поведенческие	Новое значение в существующем перечислении, например `error_code` или `billing_status`; изменённое значение по умолчанию	Обычно нет, но может сломать исчерпывающее сопоставление.
Ломающие	Удаление или переименование поля, смена типа, изменение смысла статуса, требование нового заголовка	Требуют новой версии.
Контрактные	Документация неверно описывала поведение API	Нет — но см. ниже.

Аддитивные изменения включают новые члены существующих перечислений. Клиент, который исчерпывающе разбирает status, error_code или billing_status и падает при нераспознанном значении, сломается на изменении, которое по политике не является ломающим.

Считайте неизвестное значение отдельным, но допустимым случаем: залогируйте его и перейдите к обобщённой обработке для этого класса исходов. Самый безопасный вариант по умолчанию для неизвестного error_code — тот, что эта документация предписывает для internal_error: исход неизвестен, поэтому повторите с тем же Idempotency-Key.

Когда меняется документация

Документацию правят на месте, когда поведение API было описано неверно. Это изменение документации, а не контракта: API не менялся, менялось описание. Поскольку исправление — ровно то событие, которое нельзя увидеть в записи журнала вида «ничего не изменилось», исправления перечисляются явно в журнале изменений.

Если исправление затрагивает то, на что вы опирались, оно появляется там как примечание, а не как молчаливая правка.

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

Когда операция устаревает, в документе OpenAPI её помечают deprecated: true, а этот сайт документирует замену. Операция продолжает работать в течение периода предупреждения, и этот период указывается там, где объявлено устаревание.

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

Единственное текущее устаревание

POST /v1/realtime/detect сохранён для клиентов предрелизной версии и помечен в контракте как устаревший. Новым интеграциям следует использовать эндпоинты конкретной серии.

Это переименование, а не переработка — тело запроса и ответ имеют ту же форму:

	Прежний	Текущий
Эндпоинт	`POST /v1/realtime/detect`	`POST /v1/realtime/check/phone` или `POST /v1/realtime/check/email`
Серия	Подразумевается отправленными продуктами	Явно задана в пути и должна им соответствовать
Поле продуктов	`products` (алиас)	`product_ids`
`Idempotency-Key`	Обязательно	Обязательно

Миграция — это изменение на две строки:

# Before
curl -X POST "https://api.zelnum.com/api/v1/realtime/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","products":[47]}'

# After — the series moves into the path and the field is renamed
curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","product_ids":[47]}'

Отправка product_ids и products в одном запросе отклоняется как 400 invalid_realtime_request, поэтому их нельзя смешивать при поэтапном развёртывании.

Дальше

OpenAPI — машиночитаемый контракт, включая флаг deprecated
Журнал изменений — что и когда изменилось