Wersje i wycofywanie funkcji

Niniejsze zasady dotyczą całego API integracyjnego: REST API v1, widgetu, webhooków wychodzących i przychodzących oraz SCIM 2.0. Wewnętrzne wywołania używane przez portale Core, Workspace i Desk nie są nimi objęte i mogą zmienić się w dowolnym momencie: nie należy ich używać w integracjach.

Wersje główne

• Wersja główna jest częścią ścieżki: /api/v1/…. Każda odpowiedź z /api/v1 zawiera X-Exo-API-Version: 1.
• Wersja v1 jest stabilna. W ramach v1 wprowadzamy wyłącznie zmiany zgodne wstecz:
  • nowe endpointy, nowe opcjonalne pola w żądaniach, nowe parametry zapytań;
  • nowe pola w odpowiedziach: Państwa klient musi ignorować nieznane pola;
  • nowe typy zdarzeń webhooków: Państwa system musi ignorować nieznane zdarzenia;
  • nowe kody błędów: nieznane kody należy obsługiwać na podstawie stanu HTTP;
  • nowe opcjonalne nagłówki.
• Zmiana niezgodna wstecz wymaga nowej wersji głównej (/api/v2). Niezgodne wstecz jest usunięcie lub zmiana nazwy pola, endpointu lub zdarzenia, zmiana typu, uczynienie pola opcjonalnego obowiązkowym lub zmiana uwierzytelniania.
• Po wydaniu nowej wersji głównej poprzednia pozostaje dostępna przez co najmniej 12 miesięcy.

Wycofywanie funkcji

• Wycofywana funkcja działa nadal przez co najmniej 6 miesięcy od ogłoszenia.
• Odpowiedzi korzystające z wycofywanej funkcji zawierają:
  • Deprecation: @<unix-seconds>: kiedy ogłoszono wycofanie (RFC 9745);
  • Sunset: <HTTP-date>: kiedy funkcja przestanie działać (RFC 8594);
  • Link: <url>; rel="deprecation": przewodnik po migracji.
• Każde wycofanie jest opisane w dzienniku zmian i oznaczone jako deprecated w specyfikacji OpenAPI.

Bieżące wycofania

Funkcja	Ogłoszono	Przestaje działać	Czego użyć zamiast niej
Klucze API nh_…	1 listopada 2026	30 czerwca 2027	Klucze nhk.<keyid>.<secret>
Podpis X-NH-Signature w webhookach wychodzących	1 listopada 2026	30 czerwca 2027	X-Exo-Signature z X-Exo-Timestamp
Podpis X-NH-Connector-Signature w webhookach przychodzących	1 listopada 2026	30 czerwca 2027	X-Exo-Signature z X-Exo-Timestamp
Pola event, timestamp, source w treści webhooków	1 listopada 2026	30 czerwca 2027	type, created_at, data

Specyfikacja i dziennik zmian

• Specyfikacja OpenAPI stanowi kontrakt. Jej wersja jest zgodna z wersjonowaniem semantycznym 1.MINOR.PATCH: MINOR rośnie przy zgodnych wstecz dodatkach, PATCH — przy samych poprawkach dokumentacji.
• Każda zmiana API aktualizuje wersję specyfikacji i dodaje wpis do dziennika zmian.