Résumé

  • RFC 9745, publié en mars 2025, a défini l’en-tête Deprecation avec une date au format Structured Fields. La ressource peut continuer à fonctionner après cette date.
  • Une relation Link nommée deprecation peut conduire à la politique ou au guide de migration avant même l’annonce datée. RFC 8594, paru en 2019, avait créé Sunset pour l’indication distincte d’un arrêt attendu.
  • L’avis concerne d’abord la ressource qui le porte. Un périmètre plus large demande des règles publiées par l’API. Des réponses conservées et datées permettraient de mesurer son usage réel.

Une machine qui marche peut porter son propre avis de retraite

Un service peut être parfaitement disponible au moment où son exploitant décide de préparer son départ. Les requêtes réussissent et les contrôles de disponibilité restent verts. Les nouveaux clients devraient pourtant choisir une autre voie ; les anciens devront déplacer leurs dépendances. Si l’annonce n’existe que sur une page de politique, le développeur qui inspecte le trafic peut passer à côté. Si elle n’apparaît qu’au moment de la panne, la migration commence trop tard.

RFC 9745 a placé l’avis dans la réponse HTTP. L’en-tête Deprecation décrit la ressource identifiée par cette réponse. Sa valeur est une date au format Structured Fields, par exemple Deprecation: @1688169599. Dans l’exemple normatif, elle correspond au 30 juin 2023 à 23 h 59 min 59 s UTC. Une date future annonce l’entrée en dépréciation ; une date passée indique qu’elle a déjà eu lieu. Le serveur peut continuer à répondre normalement dans les deux cas.

Cette simultanéité change le travail des clients. Un logiciel peut obtenir aujourd’hui les mêmes données qu’hier tout en recevant un avertissement sur la durée de sa dépendance. Le texte de RFC 9745 précise que la dépréciation ne modifie pas le comportement de la ressource. Le signal s’adresse à l’équipe qui planifie, pas à un interrupteur qui coupe aussitôt la requête.

Le périmètre exige de la précision. Par défaut, le champ décrit la ressource associée à la réponse. Un fournisseur peut vouloir annoncer le retrait de toute une API ou d’un groupe de chemins, mais il doit définir comment l’avis d’une ressource s’étend aux autres. Sans règle explicite, une réponse isolée ne donne pas une carte complète du service. L’exploitant contrôle la surface qu’il avertit et l’étendue qu’il explique.

Le mode d’emploi peut précéder la date

La même RFC a enregistré une relation Link appelée deprecation. Elle mène à une documentation sur la politique, le remplacement ou le calendrier. Elle peut figurer dans les réponses avant l’en-tête daté. Les développeurs peuvent ainsi découvrir la manière dont l’exploitant prévoit d’annoncer une future dépréciation, pendant que la ressource est encore pleinement recommandée.

Une date seule ne résout guère la migration. Il faut savoir quelle ressource la remplace, si les permissions changent, ce qu’il advient des données et combien de temps les anciennes versions resteront utilisables. Le lien peut conduire vers cette explication depuis l’interface en production. La qualité de l’explication dépend toujours de celui qui la publie. Une notice portable ne répartit pas les coûts de migration : elle les rend visibles.

Deux horloges, deux décisions

RFC 8594, de mai 2019, avait défini Sunset. Cet en-tête annonce la date à laquelle une ressource devrait cesser de répondre. Il emploie le format de date HTTP. Deprecation vise un autre moment : celui où l’exploitant décourage de nouvelles dépendances, alors que la ressource peut encore servir. Le premier avertit sur le choix architectural ; le second sur la disponibilité attendue.

RFC 9745 autorise les deux en-têtes et impose que la date Sunset ne précède pas celle de Deprecation. Son exemple échelonne la dépréciation au 30 juin 2023 et l’arrêt attendu au 30 juin 2024. Renverser ces dates reviendrait à annoncer que la ressource disparaîtra avant d’entrer en dépréciation. Les syntaxes trahissent aussi leur histoire : Deprecation utilise une date Structured Fields précédée de @, Sunset conserve une date HTTP traditionnelle.

Les deux dates sont des indications de calendrier publiées par le fournisseur. L’utilité pour les clients vient d’un périmètre clair, d’un remplaçant testable et d’un exploitant qui agit selon sa propre annonce. Il manque des captures datées de réponses de services précis pour établir où le nouvel en-tête a effectivement circulé. Le texte de 2025 suffit à montrer le changement : une API encore opérationnelle peut transmettre son avis de sortie dans le canal même où elle rend service.