Changer de version d’API en suivant les flux de données

Planifiez le changement d’une interface de programmation (API) à partir des flux de données concernés. Le nouveau point de terminaison n’est qu’une partie de la migration : les champs, les autorisations et l’interprétation des réponses doivent aussi convenir au système appelant.

Recenser les appelants concernés

Dans une entreprise fictive, un portail client et un import nocturne envoient des commandes à la même API. Migrer uniquement le portail laisserait le second appelant sur l’ancienne version. Pour chaque appelant, notez les fonctions utilisées et la personne qui peut effectuer sa migration. Utilisez les informations de modification et d’arrêt du fournisseur réel ; un numéro de version ne fixe pas de délai de migration universel.

Google AIP-180 distingue la compatibilité du code source, des échanges et de la sémantique. Ces recommandations aident à examiner les changements ; elles ne garantissent pas le comportement de n’importe quelle API tierce.

Décrire le changement avec un exemple concret

Dans notre exemple, l’ancienne requête transporte du texte dans le champ delivery_note. La nouvelle version attend ce texte sous delivery_note.text. Les deux doivent transmettre la même consigne de livraison, « Tor B ». Remplacer une URL ou établir une connexion ne suffit donc pas pour cette migration.

Vérifiez aussi comment sont signalés les erreurs et les traitements encore en cours. Une structure de réponse différente peut affecter l’appelant, même si la requête reste acceptée.

Comparer ancien et nouveau dans les mêmes conditions

Dans un environnement de test adapté, préparez une commande normale et un cas sans consigne de livraison. Comparez les données cibles enregistrées et la réponse visible. Vérifiez également si les droits d’accès utilisés couvrent les deux versions. Pour cette comparaison, les commandes réelles ne doivent pas être envoyées sur deux chemins de production.

Coordonner la bascule avec les opérations ouvertes

Définissez à partir de quel point les nouvelles requêtes empruntent le nouveau chemin. Les requêtes déjà envoyées mais non confirmées nécessitent une correspondance pour qu’une répétition ne devienne pas une nouvelle commande. Convenez d’un retour à l’ancien chemin pour les nouvelles requêtes et examinez séparément le sort des données déjà écrites. Rétablir une URL n’annule pas ces modifications.

L’ancienne version peut sortir de ce flux lorsque tous les appelants recensés ont migré et que les opérations ouvertes ont leur correspondance. Documentez l’état réellement vérifié plutôt que la seule nouvelle étiquette de version.

Sources

• Google AIP-180: Backwards compatibility