Article

Versionner une API : dépréciation et migration des clients

Versionner une API utilisée par des agents : rendre le contrat identifiable, annoncer le retrait avec Deprecation et Sunset, puis guider la migration.

Vous devez faire évoluer votre API : l’identifiant d’une commande, jusqu’ici un nombre, devient une chaîne de caractères, mais le champ garde le même nom. Un client écrit pour l’ancien contrat, agent compris, peut continuer à l’interpréter selon l’ancienne documentation et se tromper sans erreur visible. Rendez le contrat identifiable dans les échanges, annoncez la dépréciation de l’ancien contrat et la date de son retrait avec un guide de migration, et préparez un refus compréhensible pour l’après-retrait.

L’exemple d’une API fictive de commandes va du client qui casse jusqu’au refus final : ce qui casse et pourquoi, comment le client sait quel contrat il reçoit, l’annonce du retrait, la migration d’un agent, puis le refus de l’ancienne route.

Un identifiant qui change de format casse un client sans changer de nom

Dans le contrat v1 de cette API fictive, une commande se lit {"id":42}. Le contrat v2 renvoie {"id":"cmd_42"}. Un client v1 qui convertit l’identifiant en entier échoue. Le champ s’appelle toujours id : rien dans son nom ne signale le changement.

Ce changement de type reste visible pour un programme qui vérifie les types. Un changement de sens peut casser autant sans laisser de trace : un montant exprimé dans une autre unité reste un nombre, mais le client prend une mauvaise décision. Le guide AIP-180 de Google distingue pour cette raison trois compatibilités : celle du code, qui doit encore compiler et fonctionner avec la nouvelle version de la bibliothèque cliente ; celle des échanges, qui doivent encore être compris par le nouveau serveur ; et celle du comportement, qui doit encore donner ce qu’un développeur raisonnable attend. Il ajoute que le code dépend souvent de comportements qui n’ont jamais été explicitement promis ni documentés. Depuis octobre 2025, il interdit aussi, au sein d’une même version, de changer le format attendu de la valeur d’un champ existant : un tel changement demande une nouvelle version.

Le service conserve donc v1 pendant la transition. Changer silencieusement le type du même champ romprait son contrat. Un agent ajoute une difficulté : il s’appuie sur les exemples, la documentation et les réponses qu’il a déjà lus, et ces informations peuvent être anciennes. Il faut lui permettre de vérifier, au moment d’agir, quel contrat le serveur applique.

Le client doit savoir quel contrat il reçoit

Une version peut figurer dans l’URL, comme /v1/commandes/42, dans un en-tête ou dans un type de média. Ces choix de forme ne déterminent pas à eux seuls la taille des changements ni la qualité de la migration. Dans tous les cas, le client doit savoir quelle version il demande et laquelle le serveur applique.

Une version datée peut aider à identifier précisément un ensemble de comportements. Stripe a décrit cette approche en 2017 : des versions nommées par leur date de publication, comme 2017-05-24, et un compte fixé sur la version la plus récente lors de sa première requête. Sa documentation actuelle montre l’évolution : depuis la version 2024-09-30.acacia, Stripe publie chaque mois une version sans changement incompatible et, deux fois par an, une version majeure, comme Basil, qui commence par des changements incompatibles. Le point utile pour le client est cet engagement : il sait quelles mises à jour peuvent toucher son code et lesquelles ne le peuvent pas.

La même documentation précise qu’une requête HTTP qui n’envoie pas d’en-tête Stripe-Version utilise la version par défaut du compte ; les bibliothèques clientes récentes de Stripe fixent, elles, la version en vigueur à leur publication. Une version par défaut est commode, mais si elle était modifiée silencieusement, le même appel donnerait un autre résultat sans que le client ait rien changé, et ce résultat serait difficile à expliquer.

Annoncer la dépréciation, puis le retrait

Dans l’API de l’exemple, la dépréciation de v1 prend effet le 1er octobre 2026 et son retrait est prévu le 1er décembre 2026 ; ces dates sont fictives. Le 9 octobre, une lecture v1 réussit encore et annonce la transition :

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1790812800
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example/migrations/commandes-v2>; rel="deprecation"

{"id":42,"statut":"preparee"}

Trois en-têtes portent l’annonce. L’en-tête Deprecation, défini par la RFC 9745, indique qu’une ressource est ou sera dépréciée, à la date donnée. Sa valeur est une date au format des champs structurés de HTTP, un nombre de secondes écoulées depuis le 1er janvier 1970 précédé de @ (RFC 9651, §3.3.7) : @1790812800 correspond au 1er octobre 2026 à minuit UTC. Être dépréciée ne signifie pas avoir cessé de fonctionner : la RFC précise que la dépréciation ne change pas le comportement de la ressource, et la lecture réussit comme avant.

L’en-tête Sunset, défini par la RFC 8594, annonce la date à laquelle la ressource devrait cesser de répondre. Il utilise une date HTTP, un format différent pour des raisons historiques, et la RFC 9745 interdit qu’il précède la date de dépréciation. L’en-tête Link, avec la relation deprecation, conduit à la documentation du retrait, ici un guide de migration. Le client doit interpréter chaque date selon sa propre spécification.

Ces en-têtes annoncent une politique, sans garantir à eux seuls que le service sera accessible jusqu’à la seconde indiquée. La RFC 8594 demande de traiter la date de Sunset comme un indice : rien ne garantit que la ressource restera disponible jusque-là, ni qu’elle disparaîtra après. La RFC 9745 rappelle qu’un client doit pouvoir fonctionner sans ces informations. Elles complètent les annonces aux développeurs et la surveillance des usages ; elles ne réalisent pas la migration à la place du client.

L’agent migre en suivant le guide que la réponse désigne

L’agent qui reçoit cette réponse suit le lien deprecation et consulte le guide que le service lui désigne, plutôt qu’une page trouvée ailleurs ou ce qu’il croit savoir de l’API. Il y apprend que l’identifiant devient opaque : une chaîne à recopier, dont le client ne doit déduire ni le format ni la valeur suivante. Il utilise la correspondance entre anciens et nouveaux identifiants que fournit le service. Il ne fabrique pas cmd_42 en ajoutant un préfixe à 42 : cette valeur n’est qu’un exemple, et rien ne promet que cette règle de construction tienne.

Avant de changer le contrat qu’utilise sa mission, il vérifie en v2 la lecture, la modification et le traitement d’une erreur. Une nouvelle version peut modifier le sens des données ou des actions autant que leur forme : changer la valeur de version dans l’appel ne suffit pas.

Après le retrait, un refus qui explique

Le 1er décembre, la route v1 est retirée de façon permanente. Le service répond alors 410 Gone, le code d’une ressource qui n’est plus disponible et dont l’absence est probablement définitive (RFC 9110, §15.5.11), avec un corps qui explique le retrait, indique les versions prises en charge et redonne le lien de migration. Le code de statut dépend de ce qui est retiré : 410 Gone convient à une ressource retirée de façon permanente, mais il ne remplace pas une politique d’erreur adaptée à toutes les formes de négociation de version, par exemple une version demandée par un en-tête que le serveur ne prend plus en charge.

Avec ce refus, un client peut déterminer s’il sait utiliser une autre version. Ne lui demandez pas de changer aveuglément une valeur de version : l’agent qui ne comprend pas v2 s’arrête avec une explication, et celui qui sait l’utiliser recommence la lecture et reconstruit son action depuis le nouveau contrat. S’il avait envoyé une écriture juste avant le retrait sans en recevoir la réponse, il ne rejoue pas automatiquement une écriture dont l’effet précédent est inconnu : il vérifie d’abord ce qu’elle a produit.

Les liens évitent de figer les adresses

Dans ce parcours, l’agent n’a pas construit l’adresse du guide : il l’a trouvée dans la réponse. Une réponse hypermédia peut aller plus loin et fournir, par des liens et des formulaires, 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. Roy Fielding, qui a défini REST, écrivait en 2008 qu’une API REST ne doit pas imposer au client des noms de ressources ni des hiérarchies fixes, et qu’un client doit pouvoir y entrer avec la seule adresse initiale et des types de média standardisés. En 2014, interrogé sur le versionnement, il déconseillait d’inscrire dans les noms de l’interface des numéros de version visibles du client, qui servent selon lui le propriétaire de l’API plus que ses clients. Pour les ruptures radicales qui imposent une API complètement différente, quand le sens de l’interface change ou qu’un problème de sécurité oblige à abandonner le logiciel déployé, il parle d’un nouveau système plutôt que d’une nouvelle version, distingué par son nom d’hôte.

Le client doit pourtant 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. L’identifiant devenu opaque en est un exemple : aucun lien ne dispense le client de cesser de le traiter comme un nombre. Dans cet exemple, le service garde v1 et v2 côte à côte pendant la transition et rend la version visible dans l’échange, pour que l’ancien client voie dans la réponse que le sens de l’identifiant change. Ce choix vaut pour ce cas ; il ne fait pas d’un numéro de version dans l’adresse une règle générale. Un agent qui parcourt l’API par ses liens profite de cette découverte, à condition que les informations restent lisibles et que les erreurs lui permettent de reprendre.

Recetter la transition avec un client v1

La recette garde un client v1 pendant toute la transition. Elle vérifie le signal de dépréciation, puis le refus final, et vérifie qu’un client v2 traite l’identifiant comme une chaîne opaque. Elle porte ainsi sur le comportement, pas seulement sur la syntaxe, ce que l’AIP-180 appelle la compatibilité de comportement. Le trafic par version indique ensuite quels consommateurs restent à migrer.

Dans ce parcours, le client v1 n’a pas reçu cmd_42 sous son ancien contrat. L’ancien contrat a répondu tant qu’il était promis, en annonçant sa fin, puis a refusé en expliquant où aller. L’agent qui savait utiliser v2 a migré en suivant le guide que la réponse lui désignait ; celui qui ne le savait pas s’est arrêté avec une explication plutôt que de deviner.

Sources

Explorer

Sur le même sujet

Choisis dans l’index d’après les étiquettes de cet article — les plus proches d’abord, hors de sa série. Rien n’est écrit à la main : un article publié demain avec les mêmes étiquettes y prendra place.

Laisser un commentaire

Elle n'est jamais affichée ni publiée. Elle sert à regrouper vos commentaires et, si vous vous inscrivez un jour avec elle, à vous les rendre.

Votre commentaire sera relu avant d'être publié.