Versions et dépréciation de l'API

Nous vous demandons de faire pointer vos propres scripts, intégrations et bibliothèques clientes Zendesk vers ChaosDesk. Cette page est la promesse qui va avec : ce que nous pouvons changer, ce que nous ne pouvons pas changer et combien de temps à l’avance vous êtes prévenu. Elle couvre l’API REST sous /api, l’API compatible Zendesk sous /zd/api/v2 et le contrat des webhooks. Chaque changement figure dans le journal des modifications de l’API.

En bref

Préavis avant tout retrait	12 mois
Versions de l’API REST	Aucune dans l’URL : /api ne fait que grandir
Numéro de version	info.version dans openapi.json, sémantique
API compatible Zendesk	Figée sur les formats Zendesk documentés
Webhooks	Entier version dans le payload, fixé par webhook
Annonce d’une dépréciation	Journal des modifications, en-têtes Deprecation et Sunset, deprecated dans le document OpenAPI, e-mail

Une API REST vivante, uniquement additive

/api n’est pas versionnée dans l’URL et ne le sera pas. Nous l’enrichissons à la place :

• nouveaux endpoints,
• nouveaux paramètres facultatifs de requête et de corps,
• nouveaux champs dans les réponses.

Écrivez votre client pour qu’il ignore les champs qu’il ne connaît pas, et les nouveaux champs ne poseront jamais problème. En échange, nous ne supprimons jamais un champ, ne changeons jamais son type sur place et ne rendons jamais obligatoire un paramètre existant.

La version à citer dans un rapport de bug est info.version du document OpenAPI. Elle est sémantique : le numéro de correctif augmente pour les corrections, le numéro mineur pour les ajouts, et le numéro majeur seulement avec la règle ci-dessous.

Si quelque chose doit casser

Un changement incompatible arrive à côté de l’ancien format, jamais à sa place. Le nouveau format apparaît soit comme un nouveau champ, soit sous un nouveau chemin pour les seules ressources concernées (/api/v2/<resource>), et l’ancien continue de fonctionner pendant tout le préavis ci-dessous. Nous n’utilisons pas d’en-tête de version daté : il multiplie les comportements par endpoint, et nos bibliothèques clientes générées fixent des chemins, pas des en-têtes.

L’API compatible Zendesk est figée

/zd/api/v2 existe pour que les clients écrits pour Zendesk continuent de fonctionner. Le v2 est la version de Zendesk, pas la nôtre. Sur cette surface, nous ne faisons qu’ajouter des endpoints et des champs, et nous ne changeons jamais une réponse que le client d’un autre éditeur analyse. Nous nous engageons sur les formats documentés sur la page de l’API compatible Zendesk, et des tests de contrat les protègent à chaque build. Si Zendesk modifie sa propre API, la nôtre reste telle que documentée et l’écart est consigné dans le journal des modifications.

Versions du payload des webhooks

Chaque livraison et chaque ping de webhook portent un entier version dans leur enveloppe. Il vaut 1 aujourd’hui et fait partie du contrat public.

• Une enveloppe incompatible reçoit un nouvel entier, jamais une modification d’un entier existant.
• La version est choisie par abonnement de webhook : un webhook existant garde l’enveloppe pour laquelle il a été conçu.
• Pendant le retrait d’une version, les deux sont livrées pendant tout le préavis.
• Les types d’événements sont additifs. Un abonnement à un type d’événement que vous ne connaissez pas n’échoue jamais.
• Si le schéma de signature change un jour, la nouvelle signature arrive dans un nouvel en-tête et les deux sont envoyées pendant le préavis.

12 mois de préavis

Le retrait d’un endpoint, d’un champ, d’un type d’événement ou d’une version d’enveloppe de webhook sur l’une des trois surfaces est annoncé au moins 12 mois à l’avance.

« Annoncé » signifie tout ceci, pas seulement le premier point :

1. une entrée sous Déprécié dans le journal des modifications de l’API, avec la date prévue du retrait ;
2. des en-têtes de réponse Deprecation et Sunset (RFC 8594) sur les opérations concernées, pour qu’un client le voie sans rien lire ;
3. deprecated: true sur l’opération ou le champ dans le document OpenAPI ;
4. un e-mail aux propriétaires des espaces de travail et aux propriétaires des tokens d’API qui ont appelé l’endpoint au cours des 90 derniers jours.

Les en-têtes ressemblent à ceci :

HTTP/1.1 200 OK
Deprecation: Thu, 12 Mar 2026 00:00:00 GMT
Sunset: Fri, 12 Mar 2027 00:00:00 GMT
Link: <https://chaosdesk.io/developers/api-changelog>; rel="deprecation"; type="text/html"

Deprecation indique quand nous l’avons annoncé, Sunset le premier moment où l’opération peut cesser de répondre.

La seule exception est un changement imposé par un problème de sécurité ou juridique. Il bénéficie d’autant de préavis qu’il est sûr d’en donner, jamais moins de 7 jours, et toujours d’un e-mail direct en plus d’une entrée au journal des modifications.

Ce qui n’est pas couvert

• Les endpoints propres à l’application agent (/mobile-api) sont internes à nos apps et évoluent avec elles. Ne construisez rien dessus ; l’API REST a les mêmes données.
• Les endpoints bêta, quand nous en proposons, sont marqués bêta dans le journal des modifications et ne relèvent de la règle des 12 mois que lorsque le journal le dit. Rien n’est bêta par défaut : tout ce qui figure dans la référence de l’API sans mention bêta relève de la politique complète.
• Un comportement qui a toujours été un bug. Corriger une réponse qui contredisait cette documentation est une correction, livrée dans une version corrective avec une entrée au journal des modifications.

Rester à jour

• Suivez le journal des modifications de l’API : chaque changement y est écrit en premier.
• Régénérez ou mettez à jour votre bibliothèque cliente quand le numéro mineur de la version OpenAPI change ; les clients sont générés depuis ce document.
• Journalisez les en-têtes Deprecation et Sunset dans votre intégration. Ce sont les premiers avertissements lisibles par machine que vous recevrez.

Fiche de décision : ADR 0014, versions de l’API et des webhooks et politique de dépréciation.