Compatibilité et gestion des versions

L’API DUST est versionnée dans le chemin : chaque point de terminaison se trouve sous /api/v1. Au sein d’une version, nous faisons évoluer l’API en continu, mais selon des règles strictes : les modifications sont additives par défaut, tout changement susceptible de rompre une intégration bien conçue passe d’abord par une période de dépréciation, et la spécification OpenAPI publiée constitue à tout moment la définition faisant autorité du contrat.

Cette page définit ce que signifie « bien conçue » pour votre intégration et ce que nous vous garantissons en retour.

Ce qui peut changer sans préavis

Ces modifications sont considérées comme rétrocompatibles. Elles peuvent apparaître dans n’importe quelle version publiée et votre intégration doit les prendre en charge :

De nouveaux points de terminaison et de nouvelles opérations sur les chemins existants.
De nouveaux paramètres de requête, en-têtes et champs de corps facultatifs. Les requêtes existantes continuent de fonctionner sans modification.
De nouveaux champs dans les réponses. Les objets s’enrichissent au fil du temps.
De nouvelles valeurs dans les champs énumérés — de nouveaux types d’événements, états et types sont ajoutés à mesure que le produit évolue.
De nouveaux codes d’erreur pour des modes d’échec qui étaient auparavant signalés par un code générique.
La documentation, le texte message des erreurs et l’ordre des champs. Les chaînes lisibles par l’humain ne font pas partie du contrat ; l’ordre des membres JSON n’a jamais de signification.

Écrire une intégration qui reste compatible

Les règles ci-dessus sont sans risque si votre client suit les pratiques standard d’un lecteur tolérant :

Ignorez les champs de réponse que vous ne reconnaissez pas. N’échouez jamais en présence de membres inattendus et n’utilisez pas de validation stricte du schéma qui rejette les champs inconnus.
Acceptez les valeurs d’énumération inconnues. Traitez les valeurs que vous prenez en charge et gérez proprement par défaut celles que vous ne prenez pas en charge.
Basez vos branchements sur le code d’erreur, jamais sur le message. Les codes sont des identifiants stables ; les messages sont localisés et peuvent être reformulés. Consultez les Conventions relatives aux requêtes.
Traitez les ID et les curseurs de pagination comme des chaînes opaques. Conservez-les et réutilisez-les tels quels ; ne les analysez ni ne les construisez jamais.
Appelez uniquement ce qui est documenté dans la spécification publiée. Les points de terminaison, champs et comportements absents de la spécification OpenAPI publique ne bénéficient d’aucune garantie de compatibilité.

Une intégration qui respecte ces règles n’est pas affectée par les modifications additives et correspond au type d’intégration protégé par les garanties ci-dessous.

Ce que nous considérons comme une rupture de compatibilité

Nous n’apportons aucune des modifications suivantes à une opération /api/v1 publiée sans suivre le processus de dépréciation décrit ci-dessous :

Supprimer ou renommer un point de terminaison, un paramètre de requête ou un champ de réponse.
Modifier le type ou le format d’un champ.
Rendre obligatoire une entrée de requête facultative ou restreindre les valeurs qu’une entrée accepte.
Supprimer une valeur d’un champ énuméré.
Modifier le code d’erreur ou le statut HTTP renvoyé pour un mode d’échec existant et documenté.
Exiger un niveau d’autorisation supérieur ou une nouvelle permission pour une opération existante.
Modifier de manière substantielle la sémantique d’une opération, même si sa structure reste inchangée.

Dépréciation

Lorsque nous devons retirer ou remanier un élément, celui-ci est d’abord déprécié :

L’opération ou le champ porte la mention deprecated: true dans la spécification OpenAPI publiée, et la dépréciation est signalée dans cette documentation.
La fonctionnalité dépréciée continue de fonctionner sans modification pendant au moins 90 jours à compter de l’annonce.
Lorsqu’une solution de remplacement existe, elle est documentée et disponible avant ou au moment de la dépréciation.

Gestion des versions

Les nouvelles versions majeures sont rares par conception. /api/v1 évolue de manière additive ; nous n’introduirions une /api/v2 que pour un remaniement impossible à réaliser de manière compatible. /api/v1 resterait alors prise en charge pendant une longue période de migration annoncée explicitement — elle ne serait jamais supprimée à l’issue de la période de dépréciation indiquée ci-dessus.

Voir aussi

Conventions relatives aux requêtes — le contrat commun relatif aux requêtes auquel s’appliquent ces garanties.
Authentification et clés d’API — comptes de service et durées de vie des jetons.
Référence complète de l’API — générée à partir de la spécification publiée.

Signaler un problème dans la documentation