Faire évoluer une API utilisée par des agents sans casser leurs parcours

Vous changez le format d'un identifiant dans votre API. Le champ garde le même nom, mais un client continue de l'interpréter selon l'ancien format. Les agents peuvent rencontrer ce problème comme les applications classiques. Une évolution fiable demande un contrat clair, une période de transition et des réponses qui aident le client à s'adapter.

Identifier ce qui peut casser un client

Supprimer un champ ou changer son type est une rupture visible. Modifier son sens peut l'être tout autant. Un montant exprimé dans une autre unité reste un nombre, mais le client peut prendre une mauvaise décision.

Le guide AIP-180 de Google distingue notamment la compatibilité du code, celle des échanges et celle du comportement. Les clients peuvent aussi dépendre d'usages qui n'ont jamais été explicitement promis.

Un agent s'appuie sur les exemples, la documentation et les réponses qu'il a déjà lus. Ces informations peuvent être anciennes. Il faut lui permettre de vérifier le contrat applicable à l'exécution.

Choisir comment identifier le contrat

Une version peut figurer dans l'URL, dans un en-tête ou dans un type de média. Ces choix ne déterminent pas à eux seuls la taille des changements ni la qualité de la migration.

Une version datée peut aider à identifier précisément un ensemble de comportements. Stripe a documenté cette approche, puis l'a fait évoluer avec des trains de versions nommés. Le point utile est l'engagement sur les changements compatibles et sur la durée de prise en charge.

Dans tous les cas, le client doit savoir quelle version il demande et laquelle le serveur applique. Une version par défaut silencieusement modifiée peut rendre les résultats difficiles à expliquer.

Annoncer la dépréciation dans les réponses

L'en-tête Deprecation, défini par la RFC 9745, indique qu'une ressource est ou sera dépréciée. Il ne signifie pas qu'elle a cessé de fonctionner.

L'en-tête Sunset, défini par la RFC 8594, peut annoncer la date à laquelle la ressource devrait devenir indisponible. Un lien peut accompagner ces informations et conduire à une politique de retrait ou à un guide de migration.

Les formats de date diffèrent : Deprecation utilise une date de champ structuré, tandis que Sunset utilise une date HTTP. Le client doit les interpréter selon leurs spécifications.

Ces signaux restent des informations que le client peut ignorer. Ils complètent les annonces et la surveillance des usages ; ils ne réalisent pas la migration à sa place.

Préparer un refus compréhensible après le retrait

Lorsqu'un contrat n'est plus accepté, donnez une erreur qui l'explique et indique où trouver les versions prises en charge. Un client peut alors déterminer s'il sait en utiliser une autre.

Ne lui demandez pas de changer aveuglément une valeur de version. Une nouvelle version peut modifier le sens des données ou des actions. L'agent doit lire les différences et vérifier qu'il peut poursuivre la tâche.

Le code de statut dépend de ce qui est retiré. 410 Gone convient à une ressource retirée de façon permanente ; il ne remplace pas une politique d'erreur adaptée à toutes les formes de négociation de version.

Utiliser les liens pour réduire les adresses figées

Une réponse hypermédia peut fournir les destinations et les actions disponibles. Le client suit ces contrôles au lieu de construire toutes les adresses à partir de souvenirs ou d'exemples.

Il doit toujours comprendre le type de média, les relations de lien et la signification des opérations. L'hypermédia réduit certaines dépendances aux chemins ; il ne rend pas compatible n'importe quel changement métier.

Un agent qui parcourt l'API peut bénéficier de cette découverte, à condition que les informations restent lisibles et que les erreurs lui permettent de reprendre.

Tester la transition avec les clients réellement utilisés

Conservez des parcours représentatifs : lecture, création, modification et traitement d'une erreur. Exécutez-les avec l'ancien contrat et le nouveau. Vérifiez aussi qu'un client ancien reçoit une information utile pendant la transition.

Suivez le trafic par version pour connaître les consommateurs qui n'ont pas migré. Définissez la date de retrait et les possibilités de retour avant de modifier le comportement par défaut.

La version n'est qu'un repère. La migration devient fiable lorsque le client peut identifier le changement, comprendre ce qu'il implique et vérifier le résultat de sa nouvelle demande.

Sources

• S. Dalal, E. Wilde, RFC 9745 — The Deprecation HTTP Response Header Field, IETF, Standards Track, mars 2025.
• E. Wilde, RFC 8594 — The Sunset HTTP Header Field, IETF, Informational, mai 2019.
• AIP-180: Backwards compatibility, Google API Improvement Proposals, créé le 23 juillet 2019 ; la section sur le changement de format, citée ici, a été ajoutée le 21 octobre 2025.
• APIs as infrastructure: future-proofing Stripe with versioning.
• Stripe, Versioning, documentation.
• Model Context Protocol — Versioning, version courante 2026-07-28.
• R. T. Fielding, REST APIs must be hypertext-driven, 20 octobre 2008.
• M. Amundsen, Roy Fielding on Versioning, Hypermedia, and REST, InfoQ, 17 décembre 2014.
• Anthropic, Models overview, documentation.