# Версіонування та припинення підтримки API

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

## Правила сумісності

| Зміна | Класифікація | Відображення в документації |
|  --- | --- | --- |
| Додавання необов'язкового поля запиту чи відповіді, операції або значення перерахування | Аддитивна | Записати в журнал змін і оновити всі локалізовані специфікації |
| Уточнення описів або виправлення прикладу без зміни поведінки під час виконання | Виправлення документації | Записувати, коли це змінює рекомендації щодо інтеграції |
| Зробити необов'язкове поле обов'язковим, видалити або перейменувати поле чи операцію, звузити допустимі значення, змінити усталену семантику | Ламальна | До видалення надати шлях міграції та окремо версіонований контракт |
| Позначити операцію як `deprecated: true` | Припинення підтримки | Указати заміну, дату оголошення та плановану дату видалення після її затвердження |


Клієнтам варто ігнорувати невідомі поля відповіді та значення перерахувань там, де це дозволяє бізнес-логіка. Це зменшує поломки від аддитивних релізів.

## Метадані припинення підтримки

Операція OpenAPI — авторитетне машинно-читне місце. Операція з припиненою підтримкою повинна містити:

- `deprecated: true`
- опис із зазначенням заміни або з прямою вказівкою, що заміни немає
- запис-оголошення в журналі змін API
- плановану дату видалення лише після затвердження власниками продукту та шлюзу


Універсальний мінімальний строк припинення підтримки зараз не гарантується. Поки дата видалення не опублікована явно, клієнтам варто вважати операцію підтримуваною, але планувати перехід із неї.

## Джерело істини

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

## Рівні перевірки

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

Перевірка відображення сторінок підтверджує, що вибрані маршрути документації завантажуються та відображаються без клієнтських помилок.

Лише авторизований smoke-тест розгорнутого API може підтвердити відповідність виробничої поведінки опублікованому контракту. Репозиторій не запускає такий тест за замовчуванням, тому в примітках до випуску потрібно окремо зазначати факт виробничої перевірки.