Версії та застарівання

Ця політика стосується всього інтеграційного API: REST API v1, віджета, вихідних і вхідних вебхуків, SCIM 2.0. Внутрішні виклики, якими користуються портали Core, Workspace і Desk, не охоплені нею і можуть змінитися будь-коли: не використовуй їх в інтеграціях.

Основні версії

• Основна версія вказана в шляху: /api/v1/…. Кожна відповідь /api/v1 містить X-Exo-API-Version: 1.
• v1 стабільна. У межах v1 ми вносимо лише сумісні зміни:
  • нові ендпоінти, нові необов’язкові поля в запитах, нові параметри запиту;
  • нові поля у відповідях: твій клієнт має ігнорувати ті, яких не знає;
  • нові типи подій вебхуків: твоя система має ігнорувати ті, яких не знає;
  • нові коди помилок: обробляй невідомі за HTTP-статусом;
  • нові необов’язкові заголовки.
• Несумісна зміна потребує нової основної версії (/api/v2). Несумісними вважаються: вилучення або перейменування поля, ендпоінта чи події, зміна типу, перетворення необов’язкового поля на обов’язкове чи зміна автентифікації.
• Коли виходить нова основна версія, попередня залишається доступною щонайменше 12 місяців.

Застарівання

• Застаріла функція продовжує працювати щонайменше 6 місяців після оголошення.
• Відповіді, що використовують застарілу функцію, містять:
  • Deprecation: @<unix-seconds>: коли оголошено про застарівання (RFC 9745);
  • Sunset: <HTTP-date>: коли функція перестане працювати (RFC 8594);
  • Link: <url>; rel="deprecation": посібник із міграції.
• Кожне застарівання описано в журналі змін і позначено як deprecated у специфікації OpenAPI.

Поточні застарівання

Функція	Оголошено	Перестане працювати	Що використовувати замість
API-ключі nh_…	1 листопада 2026 року	30 червня 2027 року	Ключі nhk.<keyid>.<secret>
Підпис X-NH-Signature у вихідних вебхуках	1 листопада 2026 року	30 червня 2027 року	X-Exo-Signature з X-Exo-Timestamp
Підпис X-NH-Connector-Signature у вхідних вебхуках	1 листопада 2026 року	30 червня 2027 року	X-Exo-Signature з X-Exo-Timestamp
Поля event, timestamp, source у тілі вебхуків	1 листопада 2026 року	30 червня 2027 року	type, created_at, data

Специфікація і журнал змін

• Специфікація OpenAPI — це контракт. Її версія відповідає семантичному версіонуванню 1.MINOR.PATCH: MINOR зростає для сумісних доповнень, PATCH — лише для виправлень документації.
• Кожна зміна API оновлює версію специфікації і додає запис у журнал змін.