Versions et dépréciations

Cette politique s’applique à toute l’API d’intégration : API REST v1, widget, webhooks sortants et entrants, SCIM 2.0. Les appels internes utilisés par les portails Core, Workspace et Desk ne sont pas couverts et peuvent changer à tout moment : ne les utilisez pas dans vos intégrations.

Versions majeures

• La version majeure figure dans le chemin : /api/v1/…. Chaque réponse de /api/v1 contient X-Exo-API-Version: 1.
• La v1 est stable. Dans la v1, nous n’apportons que des modifications compatibles :
  • nouveaux endpoints, nouveaux champs facultatifs dans les requêtes, nouveaux paramètres de requête ;
  • nouveaux champs dans les réponses : votre client doit ignorer ceux qu’il ne connaît pas ;
  • nouveaux types d’événements webhook : votre système doit ignorer ceux qu’il ne connaît pas ;
  • nouveaux codes d’erreur : traitez les codes inconnus en fonction du statut HTTP ;
  • nouveaux en-têtes facultatifs.
• Une modification incompatible exige une nouvelle version majeure (/api/v2). Sont incompatibles : supprimer ou renommer un champ, un endpoint ou un événement, changer un type, rendre obligatoire un champ facultatif ou changer l’authentification.
• Lorsqu’une nouvelle version majeure sort, la précédente reste disponible pendant au moins 12 mois.

Dépréciations

• Une fonction dépréciée continue de fonctionner pendant au moins 6 mois après son annonce.
• Les réponses qui utilisent une fonction dépréciée contiennent :
  • Deprecation: @<unix-seconds> : la date d’annonce de la dépréciation (RFC 9745) ;
  • Sunset: <HTTP-date> : la date à laquelle la fonction cessera de fonctionner (RFC 8594) ;
  • Link: <url>; rel="deprecation" : le guide de migration.
• Chaque dépréciation figure dans le changelog et est marquée deprecated dans la spécification OpenAPI.

Dépréciations en cours

Fonction	Annoncée le	Cesse de fonctionner le	À utiliser à la place
Clés API nh_…	1er novembre 2026	30 juin 2027	Clés nhk.<keyid>.<secret>
Signature X-NH-Signature sur les webhooks sortants	1er novembre 2026	30 juin 2027	X-Exo-Signature avec X-Exo-Timestamp
Signature X-NH-Connector-Signature sur les webhooks entrants	1er novembre 2026	30 juin 2027	X-Exo-Signature avec X-Exo-Timestamp
Champs event, timestamp, source dans le corps des webhooks	1er novembre 2026	30 juin 2027	type, created_at, data

Spécification et changelog

• La spécification OpenAPI fait office de contrat. Sa version suit le versionnage sémantique 1.MINOR.PATCH : MINOR augmente pour les ajouts compatibles, PATCH pour les seules corrections de documentation.
• Chaque modification de l’API met à jour la version de la spécification et ajoute une entrée au changelog.