# Версионирование и прекращение поддержки API

MoreLogin публикует машиночитаемую версию снимка контракта в `info.version` каждого документа OpenAPI. Версия использует календарный формат `YYYY-MM-DD` и обозначает контракт документации, а не сегмент версии в URL запроса.

## Правила совместимости

| Изменение | Классификация | Отражение в документации |
|  --- | --- | --- |
| Добавление необязательного поля запроса или ответа, операции либо значения перечисления | Аддитивное | Записать в журнал изменений и обновить все локализованные спецификации |
| Уточнение описаний или исправление примера без изменения поведения во время выполнения | Исправление документации | Записывать, когда это меняет рекомендации по интеграции |
| Сделать необязательное поле обязательным, удалить или переименовать поле либо операцию, сузить допустимые значения, изменить сложившуюся семантику | Ломающее | До удаления предоставить путь миграции и отдельно версионированный контракт |
| Пометить операцию как `deprecated: true` | Прекращение поддержки | Указать замену, дату объявления и планируемую дату удаления после её утверждения |


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

## Метаданные прекращения поддержки

Операция OpenAPI — авторитетное машиночитаемое место. Операция с прекращённой поддержкой должна содержать:

- `deprecated: true`
- описание с указанием замены или с прямым указанием, что замены нет
- запись-объявление в журнале изменений API
- планируемую дату удаления только после утверждения владельцами продукта и шлюза


Универсальный минимальный срок прекращения поддержки сейчас не гарантируется. Пока дата удаления не опубликована явно, клиентам следует считать операцию поддерживаемой, но планировать переход с неё.

## Источник истины

Поведение во время выполнения остаётся авторитетным. OpenAPI, примеры, локализованные копии, манифест поведения операций и журнал изменений проверяются вместе в CI, чтобы не допустить расхождения контракта.

## Уровни проверки

Успешная проверка качества репозитория подтверждает внутреннюю согласованность файлов OpenAPI, примеров, ссылок, локализованных копий и артефактов управления.

Проверка отображения страниц подтверждает, что выбранные маршруты документации загружаются и отображаются без клиентских ошибок.

Только авторизованный smoke-тест развёрнутого API может подтвердить соответствие производственного поведения опубликованному контракту. Репозиторий не запускает такой тест по умолчанию, поэтому в примечаниях к выпуску нужно отдельно указывать факт производственной проверки.