De API sunset header, en wanneer je er een moet sturen

Sunset is één enkele responseheader, gedefinieerd in RFC 8594, die een aanroeper vertelt wanneer een resource stopt met antwoorden. API-deprecatie behandelt de volledige tijdlijn van aankondigen, herinneren, brownout en uitfaseren en de bijbehorende berichten; dit gaat over het ene machineleesbare signaal in die tijdlijn, wat het daadwerkelijk zegt, en het ene geval waarin de RFC zelf zegt dat je hem niet moet sturen.

Wat zegt de Sunset-header wel, en wat zegt hij niet?

Hij bevat één HTTP-datum: het moment waarop de resource naar verwachting niet meer reageert:

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

De RFC noemt het een aanwijzing, geen garantie: hij belooft niet dat de resource tot dat tijdstip blijft werken, en hij zegt niets over hoe een storing er daarna uitziet. Aanroepers kunnen een 4xx, een redirect of helemaal geen respons krijgen; de header maakt geen onderscheid. Een tijdstip dat al in het verleden ligt, betekent “nu, of op elk moment” en niet een fout in de waarde. Niets hiervan wordt afgedwongen door het protocol. Een client die de header nooit leest, gedraagt zich precies zoals altijd, en ontdekt dat de resource weg is op dezelfde manier als hij dat toch al zou hebben gedaan.

Wanneer zou je hem daadwerkelijk moeten sturen?

Alleen zodra de resource daadwerkelijk gaat stoppen met antwoorden, niet zodra hij simpelweg niet meer de aanbevolen keuze is. De RFC is expliciet dat deprecatie in twee fasen verloopt, en het Sunset-headerveld hoort alleen bij de tweede: de API blijft volledig operationeel tijdens de eerste fase, de aankondiging dat een versie niet meer de voorkeur heeft, en het headerveld is daar niet van toepassing. Het is van toepassing zodra de versie daadwerkelijk gepland staat om niet meer te reageren.

Dat komt direct overeen met de deprecatietijdlijn: de Deprecation-header gaat vanaf dag één de deur uit, bij de aankondigingsstap; Sunset beschrijft de datum waarop het oude gedrag daadwerkelijk stopt, dezelfde datum die de vierstappentijdlijn de uitfasering noemt. Sunset op dag één versturen is niet fout, omdat de datum dan al vaststaat, maar hem sturen zonder ook een deprecatie te hebben aangekondigd, of hem instellen voor een versie waarvan jullie nog niet echt hebben besloten hem uit te faseren, vertelt aanroepers iets wat jullie zelf nog niet hebben beslist.

Heeft dit invloed op caching?

Nee, en de RFC zegt dat expliciet: Sunset en HTTP-caching lossen niet-verwante problemen op en moeten worden gelezen als aanvullend, niet overlappend. Cachingheaders zeggen wanneer een gecachte kopie veilig te hergebruiken is; Sunset zegt niets over de huidige status van de resource, alleen dat de resource zelf ophoudt te bestaan. Een respons kan volledig cachebaar zijn tot vlak voor het moment waarop hij op sunset gaat. Gebruik het ene niet om het andere te benaderen, en neem niet aan dat een lange max-age een naderende sunsetdatum tenietdoet, of andersom.

Kan één header meer dan één endpoint op sunset zetten?

De header is van toepassing op de resource die hem teruggaf, maar de RFC staat een dienst toe om een breder bereik te documenteren: een sunsetdatum op de homeresource van een API kan zo worden gedefinieerd dat de hele API verdwijnt, niet alleen die ene URL. De valkuil is dat dit alleen werkt voor aanroepers die jullie afbakeningsregel al kennen. Een aanroeper die de header op waarde leest, ziet een sunset op de ene resource die hij opvroeg en verder niets, dus een breder bereik moet ergens worden vastgelegd waar een aanroeper het kan vinden, niet worden verondersteld.

Wat hoort er naast de header mee te gaan?

Een link naar waar de uitfasering wordt uitgelegd. RFC 8594 registreert hiervoor een eigen sunset-linkrelatie: die wijst naar een resource die het uitfaseringsbeleid, de aankomende datum of hoe te migreren beschrijft, los van de kale tijdstempel van de header.

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

Die link naar jullie eigen changelog-voorbeelden of een aparte migratiepagina wijzen, maakt van een header die vrijwel geen enkele clientcode inspecteert iets wat een mens die wel gaat zoeken meteen vindt. Combineer het met de successor-version-relatie uit de deprecatieheaders en een aanroeper krijgt uit de respons alleen al zowel waar hij heen moet als wat dit vervangt.

Hoe ziet dit er van begin tot eind uit?

Stel dat v1 verdwijnt op 1 maart 2027. De deprecatieaankondiging voegt op dag één Deprecation en Link: rel="successor-version" toe aan elke v1-respons, volgens de deprecatieheaders, maar wacht met Sunset totdat de uitfaseringsdatum echt vaststaat en geen placeholder meer is. Zodra dat zo is, draagt elke v1-respons:

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"

De gateway of monitoring van een aanroeper kan onafhankelijk alarmeren op elke header: Deprecation zegt dat er een nieuwere versie bestaat, Sunset zegt dat deze een klok heeft lopen. Geen van beide headers hoeft te veranderen vóór 1 maart; wat verandert is de respons zelf, op de dag zelf, en tijdens eventuele brownoutvensters die daarvoor gepland staan.

Verandert een brownout wat de header zegt?

De headerwaarde zelf hoeft niet te veranderen voor een geplande brownout: de sunsetdatum blijft de sunsetdatum, of de resource daarvoor nu af en toe uitvalt of niet. Wat verandert is de respons, niet de header. Korte vensters van 410 Gone plannen in de weken voor de aangekondigde datum, zoals API-deprecatie beschrijft, is wat het eerste contact van een aanroeper met de storing verandert in een generale repetitie in plaats van het echte werk op de dag dat de datum van de header aanbreekt.

FAQ

Lezen echte HTTP-clients of tools de Sunset-header eigenlijk wel? Zelden, aan de clientzijde. De waarde ervan is vooral voor wie de infrastructuur tussen jullie en de aanroeper beheert: een API-gateway of een monitoringtool die je configureert om op de header te letten, kan jullie eigen team, of dat van een partner, ruim op tijd waarschuwen voordat de code van de aanroeper er ooit iets van zou merken. Behandel het als een signaal waar je zelf tooling omheen bouwt, niet een die je kunt aannemen dat de andere kant al heeft.

Is Sunset hetzelfde als Cache-Control: max-age? Nee. max-age gaat over hoe lang een gecachte kopie geldig blijft; Sunset gaat over wanneer de resource helemaal ophoudt te bestaan. Een respons kan een korte max-age dragen en een Sunset-datum die jaren verder ligt, of andersom, en geen van beide headers beperkt de andere.

Kan ik Sunset sturen voor één veld dat verdwijnt, niet het hele endpoint? Nee, de header is gebonden aan de resource, dus de URL, niet aan een veld binnen de responsebody. Gebruik voor een veld, een parameter of een enum-waarde die verdwijnt terwijl het endpoint zelf blijft bestaan, in plaats daarvan de Deprecation-header en een changelog-entry; API-deprecatie behandelt precies het aankondigen van dat soort wijziging.

Wat als de sunsetdatum moet verschuiven? Werk de headerwaarde bij en meld dat in de changelog-entry die hem oorspronkelijk aankondigde; een gepubliceerde datum stilzwijgend veranderen is hoe een aanroeper besluit dat geen van jullie datums echt is. De RFC omschrijft de waarde als een aanwijzing juist omdat datums soms verschuiven, maar een verschoven datum zonder uitleg kost je ook de volgende.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Documentatie voor ontwikkelaars, Changelog-voorbeelden