Versionen und Deprecations

Diese Richtlinie gilt für die gesamte Integrations-API: REST API v1, Widget, ausgehende und eingehende Webhooks, SCIM 2.0. Interne Aufrufe, die von den Portalen Core, Workspace und Desk verwendet werden, sind nicht abgedeckt und können sich jederzeit ändern: Verwenden Sie sie nicht in Integrationen.

Hauptversionen

• Die Hauptversion steht im Pfad: /api/v1/…. Jede Antwort von /api/v1 enthält X-Exo-API-Version: 1.
• v1 ist stabil. Innerhalb von v1 nehmen wir nur kompatible Änderungen vor:
  • neue Endpunkte, neue optionale Felder in Anfragen, neue Query-Parameter;
  • neue Felder in Antworten: Ihr Client muss unbekannte Felder ignorieren;
  • neue Webhook-Ereignistypen: Ihr System muss unbekannte Typen ignorieren;
  • neue Fehlercodes: Behandeln Sie unbekannte Codes anhand des HTTP-Status;
  • neue optionale Header.
• Eine inkompatible Änderung erfordert eine neue Hauptversion (/api/v2). Inkompatibel ist es, ein Feld, einen Endpunkt oder ein Ereignis zu entfernen oder umzubenennen, einen Typ zu ändern, ein optionales Feld zur Pflicht zu machen oder die Authentifizierung zu ändern.
• Wenn eine neue Hauptversion erscheint, bleibt die vorherige mindestens 12 Monate verfügbar.

Deprecations

• Eine als veraltet markierte Funktion funktioniert ab der Ankündigung mindestens 6 Monate weiter.
• Antworten, die eine veraltete Funktion verwenden, enthalten:
  • Deprecation: @<unix-seconds>: wann die Deprecation angekündigt wurde (RFC 9745);
  • Sunset: <HTTP-date>: wann die Funktion nicht mehr funktionieren wird (RFC 8594);
  • Link: <url>; rel="deprecation": die Migrationsanleitung.
• Jede Deprecation steht im Changelog und ist in der OpenAPI-Spezifikation als deprecated gekennzeichnet.

Laufende Deprecations

Funktion	Angekündigt	Funktioniert nicht mehr ab	Stattdessen verwenden
API-Schlüssel nh_…	1. November 2026	30. Juni 2027	Schlüssel nhk.<keyid>.<secret>
Signatur X-NH-Signature bei ausgehenden Webhooks	1. November 2026	30. Juni 2027	X-Exo-Signature mit X-Exo-Timestamp
Signatur X-NH-Connector-Signature bei eingehenden Webhooks	1. November 2026	30. Juni 2027	X-Exo-Signature mit X-Exo-Timestamp
Felder event, timestamp, source im Webhook-Body	1. November 2026	30. Juni 2027	type, created_at, data

Spezifikation und Changelog

• Die OpenAPI-Spezifikation ist der Vertrag. Ihre Version folgt dem Semantic Versioning 1.MINOR.PATCH: MINOR steigt bei kompatiblen Ergänzungen, PATCH bei reinen Korrekturen der Dokumentation.
• Jede Änderung an der API aktualisiert die Version der Spezifikation und fügt dem Changelog einen Eintrag hinzu.