Hlavička API Sunset a kdy ji odeslat

Sunset je jediná hlavička odpovědi, definovaná v RFC 8594, která volajícímu říká, kdy zdroj přestane odpovídat. Deprekace API pokrývá celý harmonogram oznámení-připomenutí-brownout-ukončení a oznámení, která k němu patří; tohle je o jediném strojově čitelném signálu v tom harmonogramu, co skutečně říká, a jediném případu, kdy samotné RFC říká, ať ho neposíláte.

Co hlavička Sunset říká, a co neříká?

Nese jediné HTTP datum, okamžik, kdy se očekává, že zdroj přestane odpovídat:

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

RFC to nazývá nápovědou, ne zárukou: neslibuje, že zdroj bude fungovat přesně do tohoto okamžiku, a nic neříká o tom, jak bude selhání vypadat poté. Volající může dostat 4xx, přesměrování, nebo žádnou odpověď; hlavička to nerozlišuje. Datum už v minulosti znamená „teď, nebo kdykoli”, ne chybu v hodnotě. Nic z toho protokol nevynucuje. Klient, který hlavičku nikdy nečte, se chová přesně jako vždycky, a zjistí, že zdroj zmizel, stejným způsobem, jako by to zjistil tak jako tak.

Kdy byste ji měli skutečně poslat?

Až když zdroj skutečně přestane odpovídat, ne když už jen není doporučenou volbou. RFC výslovně říká, že deprekace probíhá ve dvou fázích, a hlavička Sunset patří jen do té druhé: API zůstává plně funkční během první fáze, oznámení, že verze už není preferovaná, a hlavička se tam nepoužívá. Uplatní se, až je verze skutečně naplánovaná k ukončení odpovídání.

To odpovídá přímo harmonogramu deprekace: hlavička Deprecation jde ven od prvního dne, v kroku oznámení; Sunset popisuje datum, kdy staré chování skutečně skončí, což je stejné datum, které čtyřkrokový harmonogram nazývá ukončením. Poslat Sunset už první den není chyba, protože datum je už tou dobou pevně dané, ale poslat ji bez toho, že jste už oznámili deprekaci, nebo ji nastavit pro verzi, kterou jste se ještě nezavázali ukončit, říká volajícím něco, co jste ještě nerozhodli.

Ovlivňuje to cachování?

Ne, a RFC to říká přímo: Sunset a HTTP cachování řeší nesouvisející problémy a mají se číst jako doplňkové, ne překrývající se. Hlavičky cachování říkají, kdy je bezpečné použít uloženou kopii; Sunset neříká nic o aktuálním stavu zdroje, jen že zdroj sám přestane existovat. Odpověď může být plně cachovatelná až do okamžiku, kdy skončí. Nepoužívejte jedno jako náhradu druhého a nepředpokládejte, že dlouhé max-age ruší blížící se datum ukončení, ani naopak.

Může jedna hlavička ukončit více než jeden endpoint?

Hlavička se vztahuje na zdroj, který ji vrátil, ale RFC umožňuje službě zdokumentovat širší rozsah: datum Sunset na domovském zdroji API lze definovat tak, že znamená, že končí celé API, ne jen ta jedna URL. Háček je v tom, že to funguje jen pro volající, kteří už vaše pravidlo rozsahu znají. Volající, který čte hlavičku doslovně, vidí ukončení jen na tom jednom zdroji, který požadoval, a nic víc, takže širší rozsah musí být napsaný někde, kde ho volající najde, ne jen naznačený.

Co by mělo jít spolu s hlavičkou?

Odkaz na místo, kde je ukončení vysvětlené. RFC 8594 registruje vlastní link relaci sunset přesně pro tohle: odkaz na zdroj, který popisuje politiku ukončení, nadcházející datum, nebo jak migrovat, odděleně od holého data v hlavičce.

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

Nasměrování toho odkazu na vlastní příklady changelogu nebo dedikovanou migrační stránku promění hlavičku, kterou skoro žádný klientský kód nekontroluje, na něco, co člověk, který se skutečně podívá, hned najde. Zkombinujte to s relací successor-version z hlaviček deprekace a volající dostane z samotné odpovědi jak kam jít, tak čím se to nahrazuje.

Jak to vypadá od začátku do konce?

Řekněme, že v1 končí 1. března 2027. Oznámení o deprekaci první den přidá Deprecation a Link: rel="successor-version" do každé odpovědi v1, podle hlaviček deprekace, ale s Sunset počká, dokud není datum ukončení opravdu pevné, ne jen zástupné. Jakmile je, každá odpověď v1 nese:

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"

Brána nebo monitoring volajícího může upozorňovat na obě hlavičky nezávisle: Deprecation říká, že existuje novější verze, Sunset říká, že tahle má odpočet. Žádná z hlaviček se nemusí měnit před 1. březnem; co se mění, je samotná odpověď, v ten den, a během jakýchkoli naplánovaných brownout oken před ním.

Změní brownout to, co hlavička říká?

Hodnota hlavičky samotná se kvůli naplánovanému brownoutu měnit nemusí: datum ukončení je pořád datum ukončení, ať už zdroj před ním občas selhává, nebo ne. Co se mění, je odpověď, ne hlavička. Naplánování krátkých oken 410 Gone v týdnech před oznámeným datem, jak popisuje Deprekace API, je to, co promění volajícího první setkání se selháním ve zkoušku, místo skutečné věci v den, kdy nastane datum z hlavičky.

FAQ

Čtou hlavičku Sunset opravdu nějací skuteční HTTP klienti nebo nástroje? Zřídka, na straně klienta. Její hodnota je hlavně pro toho, kdo provozuje infrastrukturu mezi vámi a volajícím: API brána nebo monitorovací nástroj, který nakonfigurujete, aby hlídal hlavičku, může upozornit váš vlastní tým, nebo tým partnera, dávno předtím, než by si toho kód volajícího vůbec všiml. Berte to jako signál, kolem kterého stavíte nástroje, ne jako něco, u čeho můžete předpokládat, že to druhá strana už má.

Je Sunset totéž co Cache-Control: max-age? Ne. max-age je o tom, jak dlouho zůstává uložená kopie platná; Sunset je o tom, kdy zdroj úplně přestane existovat. Odpověď může nést krátké max-age a datum Sunset roky daleko, nebo naopak, a žádná z hlaviček tu druhou neomezuje.

Můžu poslat Sunset pro jedno pole, které mizí, ne pro celý endpoint? Ne, hlavička je vázaná na zdroj, tedy URL, ne na pole uvnitř těla odpovědi. Pro pole, parametr nebo hodnotu enumu, která mizí, zatímco endpoint sám zůstává funkční, použijte místo toho hlavičku Deprecation a záznam v changelogu; Deprekace API pokrývá oznamování přesně tohoto typu změny.

Co když se datum ukončení potřebuje posunout? Aktualizujte hodnotu hlavičky a řekněte to v záznamu changelogu, který ho poprvé oznámil; tiché měnění zveřejněného data je způsob, jak volající usoudí, že žádné z vašich dat nejsou skutečná. RFC rámuje hodnotu jako nápovědu přesně proto, že se data občas posouvají, ale posunuté datum bez vysvětlení vás stojí i to další.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Dokumentace pro vývojáře, Příklady changelogu