L'en-tête sunset d'API, et quand l'envoyer

Sunset est un en-tête de réponse unique, défini dans la RFC 8594, qui indique à un appelant quand une ressource va cesser de répondre. Dépréciation d’API couvre le calendrier complet annonce-rappel-brownout-retrait et les avis qui l’accompagnent ; ceci concerne le seul signal lisible par machine dans ce calendrier, ce qu’il dit réellement, et le seul cas où la RFC elle-même dit de ne pas l’envoyer.

Que dit l’en-tête Sunset, et que ne dit-il pas ?

Il porte une seule date HTTP, le moment où la ressource devrait cesser de répondre :

Sunset: Sat, 31 Dec 2028 23:59:59 GMT

La RFC l’appelle un indice, pas une garantie : elle ne promet pas que la ressource continuera de fonctionner jusqu’à cet horodatage, et elle ne dit rien sur la forme que prendra l’échec ensuite. Les appelants peuvent recevoir un 4xx, une redirection, ou aucune réponse du tout ; l’en-tête ne fait pas de distinction. Un horodatage déjà passé signifie « maintenant, ou n’importe quand » plutôt qu’une erreur dans la valeur. Rien de tout cela n’est imposé par le protocole. Un client qui ne lit jamais l’en-tête se comporte exactement comme avant, et découvre que la ressource a disparu de la même façon qu’il l’aurait découvert de toute façon.

Quand devriez-vous réellement l’envoyer ?

Seulement une fois que la ressource va vraiment cesser de répondre, pas simplement lorsqu’elle n’est plus le choix recommandé. La RFC est explicite : la dépréciation se déroule en deux étapes, et le champ d’en-tête Sunset n’appartient qu’à la seconde : l’API reste pleinement opérationnelle pendant la première étape, l’annonce qu’une version n’est plus préférée, et le champ d’en-tête ne s’y applique pas. Il s’applique une fois que la version est réellement programmée pour cesser de répondre.

Cela correspond directement au calendrier de dépréciation : l’en-tête Deprecation part dès le premier jour, à l’étape d’annonce ; Sunset décrit la date à laquelle l’ancien comportement va réellement s’arrêter, qui est la même date que le calendrier en quatre étapes appelle le retrait. Envoyer Sunset dès le premier jour n’est pas une erreur, puisque la date est déjà fixée à ce moment-là, mais l’envoyer sans avoir aussi annoncé une dépréciation, ou le définir pour une version que vous ne vous êtes pas réellement engagé à retirer, dit aux appelants quelque chose que vous n’avez pas encore décidé.

Interagit-il avec le cache ?

Non, et la RFC le dit directement : Sunset et le cache HTTP résolvent des problèmes sans rapport et devraient être lus comme complémentaires, pas comme se recouvrant. Les en-têtes de cache disent quand une copie en cache peut être réutilisée sans risque ; Sunset ne dit rien sur l’état actuel de la ressource, seulement que la ressource elle-même va cesser d’exister. Une réponse peut être entièrement cacheable jusqu’au moment précis où elle atteint son sunset. N’utilisez pas l’un pour approximer l’autre, et ne supposez pas qu’un max-age long annule une date de sunset qui approche, ni l’inverse.

Un seul en-tête peut-il faire disparaître plusieurs endpoints ?

L’en-tête s’applique à la ressource qui l’a renvoyé, mais la RFC permet à un service de documenter une portée plus large : une date Sunset sur la ressource d’accueil d’une API peut être définie pour signifier que l’API entière disparaît, pas seulement cette URL. Le piège, c’est que ça ne fonctionne que pour les appelants qui connaissent déjà votre règle de portée. Un appelant qui lit l’en-tête au pied de la lettre voit un sunset sur la seule ressource qu’il a demandée et rien d’autre, donc une portée plus large doit être écrite quelque part où un appelant peut la trouver, pas seulement sous-entendue.

Qu’est-ce qui devrait accompagner l’en-tête ?

Un lien vers l’endroit où le retrait est expliqué. La RFC 8594 enregistre sa propre relation de lien sunset exactement pour ça : pointer vers une ressource qui décrit la politique de retrait, la date à venir, ou comment migrer, séparément de l’horodatage brut de l’en-tête.

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2028 23:59:59 GMT
Link: <https://example.com/docs/sunset-policy>; rel="sunset"

Faire pointer ce lien vers vos propres exemples de changelog ou une page de migration dédiée transforme un en-tête que le code client de presque personne n’inspecte en quelque chose qu’un humain qui va chercher trouve immédiatement. Combinez-le avec la relation successor-version des en-têtes de dépréciation et un appelant obtient à la fois où aller et ce qui remplace celui-ci, depuis la réponse seule.

À quoi ça ressemble de bout en bout ?

Disons que v1 disparaît le 1er mars 2027. L’annonce de dépréciation le premier jour ajoute Deprecation et Link: rel="successor-version" à chaque réponse v1, selon les en-têtes de dépréciation, mais retient Sunset jusqu’à ce que la date de retrait soit vraiment fixée plutôt qu’un espace réservé. Une fois que c’est le cas, chaque réponse v1 porte :

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/docs/sunset-policy>; rel="sunset"

Le gateway ou le monitoring d’un appelant peut alerter sur chaque en-tête indépendamment : Deprecation dit qu’une version plus récente existe, Sunset dit que celle-ci a une horloge dessus. Aucun des deux en-têtes n’a besoin de changer avant le 1er mars ; ce qui change, c’est la réponse elle-même, le jour J, et pendant les éventuelles fenêtres de brownout planifiées avant.

Un brownout change-t-il ce que dit l’en-tête ?

La valeur de l’en-tête elle-même n’a pas besoin de bouger pour un brownout planifié : la date de sunset reste la date de sunset, que la ressource échoue par intermittence avant ou non. Ce qui change, c’est la réponse, pas l’en-tête. Planifier de courtes fenêtres de 410 Gone dans les semaines précédant la date annoncée, comme le décrit Dépréciation d’API, est ce qui transforme le premier contact d’un appelant avec l’échec en répétition plutôt qu’en réalité le jour où la date de l’en-tête arrive.

FAQ

Des clients HTTP ou outils réels lisent-ils vraiment l’en-tête Sunset ? Rarement, côté client. Sa valeur est surtout pour qui exploite l’infrastructure entre vous et l’appelant : une passerelle API ou un outil de monitoring que vous configurez pour surveiller l’en-tête peut alerter votre propre équipe, ou celle d’une partenaire, bien avant que le code de l’appelant ne le remarque jamais. Traitez-le comme un signal autour duquel vous construisez de l’outillage, pas comme un signal dont vous pouvez supposer que l’autre côté dispose déjà.

Sunset est-il la même chose que Cache-Control: max-age ? Non. max-age concerne la durée pendant laquelle une copie en cache reste valide ; Sunset concerne le moment où la ressource cesse d’exister complètement. Une réponse peut porter un max-age court et une date Sunset à des années de distance, ou l’inverse, et aucun des deux en-têtes ne contraint l’autre.

Puis-je envoyer Sunset pour un seul champ qui disparaît, pas tout l’endpoint ? Non, l’en-tête est limité à la ressource, c’est-à-dire l’URL, pas à un champ à l’intérieur du corps de sa réponse. Pour un champ, un paramètre ou une valeur d’énumération qui disparaît alors que l’endpoint lui-même reste actif, utilisez plutôt l’en-tête Deprecation et une entrée de changelog ; Dépréciation d’API couvre l’annonce de ce type de changement précisément.

Et si la date de sunset doit bouger ? Mettez à jour la valeur de l’en-tête et dites-le dans l’entrée de changelog qui l’avait annoncée en premier lieu ; changer silencieusement une date publiée est la façon dont un appelant décide qu’aucune de vos dates n’est réelle. La RFC présente la valeur comme un indice précisément parce que les dates bougent parfois, mais une date déplacée sans explication vous coûte la suivante aussi.

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