Aller au contenu principal

Compatibilité et versioning

Référence contractuelle​

La spécification OpenAPI publiée pour l'environnement concerné constitue la référence technique pour :

  • les routes ;
  • les payloads ;
  • les paramètres ;
  • les codes HTTP ;
  • les modèles de réponse ;
  • les schémas de sécurité.

Version majeure dans l'URL​

Les APIs sont versionnées par le chemin. La version majeure apparaît dans la route.

GET /v1/flows/{flowId}
GET /v1/directory-line/code:{addressing-identifier}
POST /v1/tenants/{tenantSlug}/provision

Lorsqu'un changement incompatible doit être introduit, une nouvelle version majeure peut coexister avec la précédente pendant une période de transition.

GET /v1/flows/{flowId}
GET /v2/flows/{flowId}

Évolutions compatibles​

Sont généralement considérés comme compatibles lorsqu'ils n'imposent aucune modification aux intégrations existantes :

  • ajout d'un champ optionnel dans une réponse ;
  • ajout d'un champ optionnel dans une requête ;
  • ajout d'un endpoint ;
  • ajout d'un paramètre de recherche optionnel ;
  • ajout d'un code d'erreur documenté sans modification du format existant ;
  • clarification documentaire sans changement du contrat technique ;
  • ajout d'un statut non bloquant lorsque les clients savent ignorer ou journaliser les valeurs inconnues.

Changements incompatibles​

Peuvent nécessiter une nouvelle version majeure, une dépréciation ou un plan de migration :

  • suppression ou renommage d'une route, d'un champ ou d'une valeur d'enum ;
  • modification du type d'un champ ;
  • champ auparavant optionnel rendu obligatoire ;
  • modification de la sémantique d'un statut ou d'un code d'erreur ;
  • modification de la structure de pagination ou filtrage ;
  • modification du modèle d'authentification, des scopes ou headers obligatoires ;
  • modification des garanties d'idempotence, de révélation one-time ou d'asynchronisme ;
  • modification d'un format d'erreur attendu.
Conception robuste

Les clients API doivent ignorer les champs inconnus dans les réponses JSON, ne pas dépendre de l'ordre des propriétés et éviter d'utiliser les messages lisibles comme clés de traitement automatique.