API Reference
Політика версіонування і застарівання (deprecation policy) API AOA: що змінюється без нової версії, заголовки Deprecation і Sunset, 90 днів до вимкнення.
Версіонування: версія в шляху (/api/v1). Зміни, що ламають сумісність, виходять лише в новій версії. Кожна відповідь API несе заголовок Link з rel="deprecation" і rel="sunset", який веде на сторінку цієї політики. Застарілий ендпоінт додатково позначається заголовками Deprecation і Sunset (RFC 9745, RFC 8594) щонайменше за 90 днів до вимкнення, а дата вимкнення дублюється в документації.
Зараз актуальна версія v1, застарілих ендпоінтів немає.
Ці зміни не ламають інтеграцію, тож виходять у v1 без попередження. Розраховуйте на них у своєму коді:
| Зміна | Як виходить |
|---|---|
| Видалення або перейменування поля | Лише в новій версії |
| Зміна типу поля чи формату значення | Лише в новій версії |
| Новий обовʼязковий параметр | Лише в новій версії |
| Видалення ендпоінта | Застарівання, щонайменше 90 днів |
Кожна відповідь API, зокрема помилки, несе заголовок Link на цю сторінку з rel="deprecation" і rel="sunset". Без заголовка Deprecation він означає «ендпоінт не застарів, ось наша політика» (RFC 9745, розділ 3.1), тож інтеграція може знайти політику, не читаючи документацію:
HTTP/1.1 200 OK
Link: </docs/api-reference/versioning>; rel="deprecation"; type="text/html", </docs/api-reference/versioning>; rel="sunset"; type="text/html"Застарілий ендпоінт і далі працює, але кожна його відповідь несе заголовки Deprecation (RFC 9745, момент оголошення) і Sunset (RFC 8594, дата вимкнення), а Link з rel="deprecation" веде на цю сторінку. Між оголошенням і вимкненням щонайменше 90 днів; дата вимкнення також зʼявляється в документації ендпоінта.
HTTP/1.1 200 OK
Deprecation: @1817078400
Sunset: Tue, 30 Nov 2027 00:00:00 GMT
Link: <https://aoa.com.ua/docs/api-reference/versioning>; rel="deprecation"Порада: логуйте відповіді із заголовком Deprecation у своїй інтеграції, тоді зміна не застане зненацька.