Versions et compatibilité

L’API a une seule version majeure, /v1, qui ne fait que s’enrichir. Une intégration écrite aujourd’hui continue de fonctionner à mesure que de nouvelles fonctionnalités arrivent : rien de ce sur quoi elle s’appuie n’est renommé, supprimé ni doté d’un nouveau sens.

Le numéro de version

L’API a un numéro de version comme 1.62.0. Il change à chaque publication :

le numéro de version mineure quand quelque chose est ajouté : un point de terminaison, un champ, un événement ;
le numéro de correctif quand une description ou le texte d’un message est corrigé et que rien d’autre ne change.

Vous pouvez à tout moment lire la version que sert une adresse :

Où	Quoi
`GET /openapi.json`	`info.version` de la spécification
Chaque événement du flux d’événements et chaque webhook	`api_version`, la version dont `data` suit le schéma

GET /v1/health a aussi un champ version, mais c’est la version de la publication Sursa qui sert l’adresse, et non la version de l’API.

Vous ne choisissez pas de version mineure : chaque requête est servie par la version actuelle. Grâce aux règles ci-dessous, c’est sans risque.

Ce qui peut changer dans /v1

Ces changements peuvent arriver dans n’importe quelle version mineure. Écrivez votre intégration de sorte qu’ils ne la cassent pas :

De nouveaux points de terminaison.
De nouveaux paramètres et champs de requête facultatifs. Les requêtes qui ne les utilisent pas se comportent comme avant.
De nouveaux champs dans les réponses, les objets et les événements.
De nouvelles valeurs d’énumération dans les réponses, comme un nouveau statut de fiche ou un nouveau type d’événement.
De nouveaux codes d’erreur et de nouveaux en-têtes de réponse.
Des limites assouplies : une longueur maximale plus grande, une plage plus large.
Des textes message d’erreurs et des descriptions reformulés.

Ce que votre code doit tolérer

Ignorez les champs que vous ne connaissez pas. N’échouez pas quand une réponse contient plus de champs que prévu, et n’utilisez pas de schémas stricts qui les rejettent.
Acceptez les valeurs d’énumération que vous ne connaissez pas. Toute énumération d’une réponse peut s’enrichir. Traitez une valeur inconnue comme « autre » plutôt que comme une erreur.
Ignorez les types d’événements que vous ne connaissez pas, dans les webhooks comme dans les flux.
Traitez les codes d’erreur inconnus selon leur statut HTTP : voir Erreurs.
Ne dépendez pas de l’ordre des champs dans les objets JSON, ni du texte exact des messages.

Ce qui ne change jamais dans /v1

Un chemin, un paramètre, un champ ou une valeur d’énumération n’est jamais renommé ni supprimé.
Le type d’un champ ne change jamais, et un champ ne prend jamais un nouveau sens, par exemple de nouvelles unités.
Une requête acceptée aujourd’hui n’est pas rejetée plus tard.
Le code de statut d’une réponse réussie reste le même.
Les codes d’erreur gardent leur sens, et le champ detail des réponses d’erreur garde sa forme.
Les types d’événements ne sont jamais renommés ni supprimés, et leur data ne fait que gagner des champs.

Changements incompatibles

Si un changement incompatible devient un jour nécessaire, il est publié sous une nouvelle version majeure, comme /v2, à côté de /v1. /v1 continue de fonctionner sans changement, et les deux coexistent.

Quand une route doit être retirée :

Elle est marquée deprecated dans la spécification et mentionnée dans le journal des modifications avec la date à laquelle elle sera désactivée.
Ses réponses portent les en-têtes Deprecation: true et Sunset: <date>.
Elle continue de fonctionner pendant au moins 180 jours après l’annonce. Les organisations dont les clés API l’utilisent sont prévenues par écrit au moins 90 jours à l’avance.
Après la date de retrait, elle répond 410 avec le code api.gone pendant encore 90 jours.

Surveillez l’en-tête Deprecation dans vos journaux ou votre supervision : c’est le premier signal qu’une route que vous utilisez va disparaître.

Rester informé

Le journal des modifications de ce portail liste chaque publication avec ce qui a été ajouté et ce qui est devenu obsolète. Avant de mettre à jour votre propre intégration, comparez son code avec les entrées publiées depuis la version pour laquelle vous l’avez écrite.