Dépréciation d'API : définition, bonnes pratiques et exemples

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

La dépréciation d'une API est le processus formel de retrait d'un endpoint, d'une version, d'un paramètre ou d'un champ de réponse. L'élément déprécié continue de fonctionner pendant une période annoncée, le temps d'indiquer aux consommateurs quoi utiliser à la place. À l'issue de cette période, il est supprimé, c'est le sunset (extinction), et ceux qui l'appellent encore obtiennent des erreurs.

C'est le contrat entre le fournisseur de l'API et ses consommateurs : ceci change, voici la date, voici le remplacement.

Le cycle de vie de la dépréciation

Le signaler en HTTP

Deux en-têtes de réponse standard rendent la dépréciation lisible par les machines. Deprecation (RFC 9745, mars 2025) indique que la ressource est ou sera dépréciée, avec une date écrite @ suivie de secondes Unix. Sunset (RFC 8594) indique quand elle doit cesser de répondre, avec une date HTTP qui ne devrait pas précéder la date de dépréciation. Un en-tête Link avec rel="deprecation" peut pointer vers la documentation.

HTTP/1.1 200 OK
Deprecation: @1780272000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/docs/v1-sunset>; rel="deprecation"; type="text/html"
Content-Type: application/json

Ces deux en-têtes sont des indications. Ils ne changent pas le comportement de l'endpoint et les clients n'en profitent que si quelque chose les lit : annoncez aussi par e-mail et dans la documentation.

Ce qui peut être déprécié

• Une version entière de l'API, comme la v1 au profit de la v2.
• Un endpoint isolé, par exemple remplacé par un nouveau chemin.
• Un paramètre de requête ou un champ de réponse, par exemple created remplacé par created_at.
• Une méthode d'authentification, comme les clés d'API au profit d'OAuth 2.0.
• Un type d'événement de webhook ou une méthode de SDK.

Bonnes pratiques

• Annoncez tôt. Laissez aux consommateurs le temps de planifier le travail. Il n'existe pas de durée universelle : GitHub, par exemple, prend en charge une version précédente de son API REST pendant au moins 24 mois après la sortie d'une nouvelle.
• Documentez le chemin de migration. Montrez la correspondance ancien vers nouveau avec des exemples de code, pas seulement « utilisez la nouvelle API ».
• Utilisez les en-têtes et un changelog. Rendez le changement repérable par les machines comme par les personnes.
• Contactez directement les consommateurs. Écrivez aux titulaires de compte et affichez un avis dans le produit. Peu de gens lisent un blog.
• Suivez qui appelle encore l'ancienne version. Journalisez l'usage par endpoint et par consommateur (clé d'API, client OAuth) pour joindre les bonnes personnes.
• Livrez d'abord le remplacement. Faites tourner l'ancien et le nouveau en parallèle et gardez les SDK à jour.
• Répétez le retrait. Une brève coupure annoncée (brownout) de l'ancienne version fait ressortir les clients oubliés avant l'arrêt réel.
• Renvoyez 410 Gone après le sunset. MDN le décrit comme une ressource qui n'est plus disponible, probablement de façon permanente. Utilisez 404 si vous ignorez si c'est permanent.

Erreurs courantes

• Retrait silencieux. Aucun préavis, des clients furieux.
• Pas de guide de migration. Les consommateurs doivent deviner la différence.
• Une fenêtre plus courte que le cycle de livraison de vos clients. Les équipes qui livrent chaque trimestre ne peuvent pas migrer en quelques semaines.
• Supprimer un champ encore utilisé. Vérifiez d'abord l'usage.
• Oublier les SDK et la documentation. Ils continuent d'envoyer les gens vers l'ancienne version.
• Déprécier sans remplacement. Les consommateurs n'ont nulle part où aller.
• Annoncer seulement sur un blog. Ajoutez en-têtes, e-mail et avis dans le produit.

Exemples d'API réelles

API REST de GitHub. Les versions sont nommées par date et choisies avec l'en-tête X-GitHub-Api-Version. Les requêtes sans cet en-tête utilisent 2022-11-28 et, quand une nouvelle version sort, la précédente reste prise en charge au moins 24 mois (documentation GitHub).

API GraphQL de GitHub. GitHub annonce les changements incompatibles du schéma au moins trois mois à l'avance et les applique le premier jour d'un trimestre. Les suppressions à venir figurent sur sa page des changements incompatibles (documentation GitHub).

Stripe. Les requêtes utilisent la version d'API par défaut du compte, sauf si vous la remplacez avec l'en-tête Stripe-Version : vous mettez à jour quand vous êtes prêt. Depuis la version 2024-09-30, Stripe publie des versions mensuelles sans changement incompatible et, deux fois par an, une version majeure avec des changements incompatibles (documentation Stripe).

Tester et superviser pendant la fenêtre de dépréciation

Tant que deux versions coexistent, contrôlez les deux. Des tests d'API qui comparent les réponses anciennes et nouvelles détectent les dérives de comportement avant vos consommateurs, et le guide d'import de cURL, HAR, Postman et OpenAPI montre comment transformer des requêtes existantes en tests de charge. La supervision d'API LoadFocus peut exécuter un check par endpoint et par version, vérifier code de statut, en-têtes et corps, et vous alerter si le remplaçant échoue ou ralentit. Les checks gratuits s'exécutent toutes les 5 minutes.

Testez aussi la nouvelle version avec le trafic cumulé des deux, car c'est ce qu'elle portera après le sunset. Les tests de charge LoadFocus exécutent des scripts JMeter et k6 pour cela.

Questions fréquentes : dépréciation d'API

Quelle durée pour une fenêtre de sunset ?

Cela dépend de vos consommateurs. Une API publique utilisée par de nombreuses équipes demande plus de temps qu'une API interne avec quelques clients connus. GitHub, par exemple, prend en charge une version précédente de son API REST pendant au moins 24 mois. Mesurez le temps dont ont besoin vos consommateurs les plus lents et ajoutez de la marge.

Quelle différence entre dépréciation et sunset ?

La dépréciation est l'annonce : cela fonctionne encore, mais ne construisez rien dessus. Le sunset est la date à laquelle cela cesse de fonctionner.

Dois-je versionner mon API ?

Oui, dès que quelqu'un en dehors de votre équipe en dépend. Les versions dans l'URL, comme /v1/, sont les plus simples à voir et à tester. Les versions par en-tête ou par date, comme chez GitHub et Stripe, gardent des URL stables mais s'utilisent plus facilement de travers.

Quel statut HTTP renvoyer pour un endpoint retiré ?

410 Gone est le plus clair. MDN précise que les clients ne doivent pas répéter les requêtes vers un 410 et que 404 convient quand vous ignorez si le retrait est permanent.

Comment savoir qui appelle encore un endpoint déprécié ?

Journalisez chaque requête avec un identifiant de consommateur, comme la clé d'API ou l'ID de client OAuth, puis comptez les appels par consommateur et par jour. Contactez d'abord les plus gros utilisateurs.

Ajouter un champ est-il un changement incompatible ?

Généralement non, c'est pourquoi les changements additifs exigent rarement une dépréciation. Supprimer un champ, le renommer ou changer sa signification, oui.