Comment déprécier une API sans perdre ses développeurs

Déprécier une API, c’est annoncer que quelque chose fonctionne encore aujourd’hui et cessera de fonctionner à une date déclarée, puis tenir les deux moitiés de cette promesse. La plupart des dépréciations échouent sur la seconde moitié : la date glisse silencieusement, ou elle arrive et les appelants qui n’ont jamais vu l’avis l’apprennent par une erreur. Une dépréciation est terminée quand chaque appelant concerné a soit migré, soit reçu, individuellement, la confirmation que ce n’est pas le cas.

Qu’est-ce que la dépréciation d’une API ?

La dépréciation est la période entre l’annonce qu’un endpoint, un champ ou une version va disparaître et sa suppression effective. Pendant cette période, l’ancien comportement continue de fonctionner, la documentation dit qu’il s’en va, et chaque réponse porte un avertissement lisible par machine. La suppression est l’événement séparé, ultérieur, souvent appelé sunset. Les deux se confondent, et cette confusion est là où le mal se produit : “deprecated” commence à signifier “peut-être déjà parti”, et les appelants cessent de faire confiance aux deux mots.

Quelle devrait être la durée d’une période de dépréciation ?

Assez longue pour qu’un appelant l’apprenne et fasse le travail, mesurée à partir du moment où l’avis l’a atteint plutôt qu’à partir du moment où vous l’avez écrit. Quatre-vingt-dix jours est le plancher courant pour une API web publique. Douze mois est normal pour tout ce qui est embarqué dans un logiciel que les utilisateurs finaux installent, parce que la correction doit aussi passer par leur processus de release. Le guide de versionnage de Google, AIP-185, demande une période de transition raisonnable et recommande 180 jours avant même de retirer une fonctionnalité bêta, et Kubernetes documente sa politique de dépréciation en nombre de releases plutôt qu’en mois, ce qui est la bonne unité quand vos appelants mettent à jour par version.

Choisissez une période, écrivez-la comme politique, et arrêtez de la décider par changement. Une politique publiée transforme chaque dépréciation d’une négociation en une application de règle.

Écrire la politique de dépréciation couvre le début de la fenêtre ; mettre fin à une version d’API couvre l’avis séparé nécessaire à la fin, quand la période s’écoule réellement et que la version arrête de fonctionner.

Le calendrier de dépréciation

Quatre dates, annoncées ensemble le premier jour. Chacune est une entrée de changelog séparée à son arrivée, donc l’histoire est racontée quatre fois à qui ne lit que le changelog.

1. Annoncer. L’entrée dit ce qui est déprécié, pourquoi, ce qui le remplace, et la date de sunset. La documentation de l’ancienne chose gagne une bannière qui lie vers la migration. Les réponses gagnent les en-têtes décrits ci-dessous.
2. Rappeler, à mi-chemin. Une seconde entrée, et un message direct à chaque appelant qui utilise encore l’ancien comportement. C’est l’étape qui a besoin de données d’usage : si vous ne pouvez pas lister qui appelle encore l’endpoint déprécié, vous ne pouvez pas le faire, et ça vaut la peine de corriger ça avant la prochaine dépréciation.
3. Brownout, peu avant la date. Renvoyez des erreurs pour l’ancien comportement pendant une courte fenêtre, une heure ou un jour, puis restaurez-le. Les appelants qui ont manqué tous les avis l’apprennent maintenant, pendant qu’il reste du temps. GitHub a utilisé des brownouts planifiés avant de retirer l’authentification par mot de passe pour l’API, et c’est l’étape individuelle la plus efficace de cette liste.
4. Sunset. Supprimez-le. L’erreur qui le remplace nomme le remplacement et lie le guide de migration. Gardez l’erreur en place longtemps ; un 404 ne dit rien à un appelant.

Que devrait dire un avis de dépréciation ?

Un avis de dépréciation dit ce qui disparaît, quand ça s’arrête, quoi utiliser à la place, et qui est concerné. Voici la forme, remplie :

GET /v1/reports/daily est déprécié et cesse de fonctionner le 1er mars 2027. Il est remplacé par GET /v2/reports?granularity=day, qui renvoie les mêmes données avec un schéma stable et de la pagination. Concerne les 214 intégrations qui ont appelé l’endpoint v1 au cours des 30 derniers jours ; si la vôtre en fait partie, vous recevrez aussi cet avis par email. Guide de migration : [lien]. Rien ne change jusqu’au 1er mars 2027. À partir de cette date, l’endpoint v1 renvoie 410 Gone avec un lien vers cette entrée.

Chaque phrase porte quelque chose dont la lectrice a besoin. Le nombre d’intégrations concernées dit à chaque lectrice si elle doit continuer à lire. “Rien ne change jusqu’à” est la phrase qui laisse celles qui ne sont pas concernées fermer l’onglet. La page exemples de changelog rassemble des entrées d’équipes qui écrivent cette forme de manière cohérente, et ça vaut la peine d’en lire trois avant d’écrire la première sienne.

Quels en-têtes un endpoint déprécié devrait-il envoyer ?

Envoyez Deprecation, Sunset et un Link vers le successeur, sur chaque réponse de l’endpoint déprécié, dès le jour de l’annonce. L’en-tête Deprecation porte la date à laquelle la dépréciation a pris effet ; l’ en-tête Sunset porte la date où l’endpoint cesse de répondre ; Link: <url>; rel="successor-version" pointe vers ce qu’il faut utiliser à la place.

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/changelog/daily-reports>; rel="deprecation"

La plupart des appelants ne liront jamais les en-têtes eux-mêmes. Leur valeur est que le client HTTP, le gateway ou le monitoring d’un appelant le peut, ce qui transforme votre dépréciation en alerte de leur côté plutôt qu’en page du vôtre. Les SDK que vous livrez devraient enregistrer un avertissement quand ils en voient un.

Qui a été informé, et comment le savez-vous ?

C’est l’étape qui décide si le sunset se passe calmement ou devient un incident de support, et c’est la plus difficile à faire avec un changelog seul. Une entrée de changelog informe tous ceux qui lisent le changelog. Une dépréciation doit atteindre les personnes spécifiques dont le code va échouer, et la façon habituelle de les trouver, ce sont les mêmes données d’usage dont a besoin le rappel à mi-chemin : les clés API, apps ou comptes qui ont appelé le comportement déprécié récemment.

La boucle qu’on exécute : l’entrée est rédigée à partir de la pull request qui ajoute la dépréciation, une personne relit la formulation et la date, et une fois publiée, l’entrée elle-même est la notification. Toute personne dont le retour via le widget sur le problème, ou la demande du remplacement, est devenu une issue GitHub que la pull request ferme reçoit un commentaire sur cette issue disant que c’est livré, avec un lien vers l’entrée. Feed et widget servent la même entrée à tous les autres, avec chaque autre entrée du changelog d’API. Ce qu’on ne fait pas, c’est laisser la dépréciation devenir “livrée” avant qu’une personne l’ait publiée ; un avis avec la mauvaise date est pire qu’aucun avis.

Quel que soit votre outillage, la question à laquelle vous devez pouvoir répondre le jour du sunset est : quels appelants utilisaient encore ça la semaine dernière, et lesquels d’entre eux avons-nous prévenus directement ? Si la réponse est “on a posté quelque chose à ce sujet”, le sunset n’est pas prêt.

Quelle est la différence entre déprécier et versionner ?

Versionner, c’est comment vous gardez disponible l’ancien comportement pendant que le nouveau existe ; déprécier, c’est comment vous retirez l’ancien. Une nouvelle version d’API sans politique de dépréciation pour la précédente est un engagement à faire tourner les deux pour toujours. Une dépréciation sans versionnage est un changement cassant avec un délai. Vous avez besoin des deux, et la version est la moitié la plus facile. GraphQL est l’exception qui vaut la peine d’être nommée : il n’y a généralement aucun numéro de version à incrémenter, et dépréciation de schéma GraphQL couvre comment un unique schéma partagé retire un champ avec une directive à la place.

FAQ

Un endpoint déprécié devrait-il continuer à fonctionner exactement comme avant ? Oui, jusqu’à la date de sunset. Les seuls changements permis sont les en-têtes ajoutés et, vers la fin, un brownout planifié annoncé à l’avance.

Quel code de statut un endpoint retiré devrait-il renvoyer ? 410 Gone, avec un corps et un en-tête Link pointant vers le remplacement et l’entrée de changelog. 404 dit que l’URL n’a jamais existé, ce qui est faux et inutile.

Peut-on raccourcir une période de dépréciation ? Seulement pour la sécurité. Si l’ancien comportement est exploitable, dites-le, raccourcissez la période, et prévenez chaque appelant concerné directement plutôt que de compter sur le changelog.

Faut-il déprécier un champ, ou seulement des endpoints entiers ? Champs, paramètres, valeurs d’enum, valeurs par défaut et en-têtes ont tous besoin du même traitement, parce que chacun peut casser un appelant correct. Un champ supprimé est la dépréciation la plus courante et la plus souvent sautée.

Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.

À voir sur changeloop : Documentation développeurs, Exemples de changelog