L'header sunset delle API, e quando inviarne uno

Sunset è un singolo header di risposta, definito nella RFC 8594, che dice a chi chiama quando una risorsa smetterà di rispondere. Deprecazione API copre l’intera timeline annuncio-promemoria-brownout-ritiro e gli avvisi che la accompagnano; questo articolo riguarda l’unico segnale leggibile da una macchina in quella timeline, cosa dice davvero, e l’unico caso in cui la RFC stessa dice di non inviarlo.

Cosa dice l’header Sunset, e cosa non dice?

Contiene una singola data HTTP, il momento in cui ci si aspetta che la risorsa smetta di rispondere:

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

La RFC la definisce un suggerimento, non una garanzia: non promette che la risorsa continuerà a funzionare fino a quel timestamp, e non dice nulla su come apparirà un eventuale guasto in seguito. Chi chiama può ricevere un 4xx, un redirect, o nessuna risposta; l’header non fa distinzioni. Un timestamp già nel passato significa “adesso, o in qualsiasi momento”, non un errore nel valore. Niente di tutto questo è imposto dal protocollo. Un client che non legge mai l’header si comporta esattamente come ha sempre fatto, e scopre che la risorsa non c’è più nello stesso modo in cui lo avrebbe comunque scoperto.

Quando dovreste inviarlo davvero?

Solo quando la risorsa sta davvero per smettere di rispondere, non quando è semplicemente non più la scelta consigliata. La RFC è esplicita nel dire che la deprecazione avviene in due fasi, e il campo header Sunset appartiene solo alla seconda: l’API resta pienamente operativa durante la prima fase, l’annuncio che una versione non è più preferita, e il campo header non si applica lì. Si applica quando la versione è effettivamente pianificata per smettere di rispondere.

Questo corrisponde direttamente alla timeline di deprecazione: l’header Deprecation viene inviato fin dal primo giorno, al passo dell’annuncio; Sunset descrive la data in cui il vecchio comportamento smetterà davvero, che è la stessa data che la timeline in quattro passi chiama ritiro. Inviare Sunset il primo giorno non è sbagliato, dato che la data è già fissata a quel punto, ma inviarlo senza aver anche annunciato una deprecazione, o impostarlo per una versione che non avete ancora davvero deciso di ritirare, dice ai chiamanti qualcosa che voi stessi non avete ancora deciso.

Interagisce con la cache?

No, e la RFC lo dice direttamente: Sunset e la cache HTTP risolvono problemi non correlati e vanno lette come complementari, non sovrapposte. Gli header di cache dicono quando è sicuro riutilizzare una copia in cache; Sunset non dice nulla sullo stato attuale della risorsa, solo che la risorsa stessa smetterà di esistere. Una risposta può essere pienamente cacheabile fino al momento esatto in cui va in sunset. Non usate l’uno per approssimare l’altro, e non date per scontato che un max-age lungo annulli una data di sunset imminente, né il contrario.

Un solo header può mettere in sunset più di un endpoint?

L’header si applica alla risorsa che lo ha restituito, ma la RFC permette a un servizio di documentare un ambito più ampio: una data di sunset sulla risorsa principale di un’API può essere definita per indicare che sparisce l’intera API, non solo quell’unico URL. Il problema è che questo funziona solo per chi chiama e conosce già la vostra regola di ambito. Chi legge l’header alla lettera vede un sunset sulla singola risorsa richiesta e nient’altro, quindi un ambito più ampio deve essere scritto da qualche parte dove chi chiama possa trovarlo, non semplicemente sottinteso.

Cosa dovrebbe accompagnare l’header?

Un link a dove il ritiro viene spiegato. La RFC 8594 registra una propria relazione di link sunset esattamente per questo: puntare a una risorsa che descrive la policy di ritiro, la data imminente, o come migrare, separatamente dal semplice timestamp dell’header.

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

Puntare quel link ai vostri esempi di changelog o a una pagina di migrazione dedicata trasforma un header che quasi nessun codice client ispeziona in qualcosa che una persona che va a cercare trova subito. Combinatelo con la relazione successor-version degli header di deprecazione e chi chiama ottiene, dalla sola risposta, sia dove andare sia cosa sostituisce questa risorsa.

Come si presenta tutto questo, dall’inizio alla fine?

Supponiamo che v1 sparisca il 1 marzo 2027. L’annuncio di deprecazione il primo giorno aggiunge Deprecation e Link: rel="successor-version" a ogni risposta v1, secondo gli header di deprecazione, ma rimanda Sunset finché la data di ritiro non è davvero fissata invece di essere un segnaposto. Una volta fissata, ogni risposta v1 porta:

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"

Il gateway o il monitoraggio di chi chiama può segnalare in modo indipendente su entrambi gli header: Deprecation dice che esiste una versione più recente, Sunset dice che questa ha un orologio che scorre. Nessuno dei due header deve necessariamente cambiare prima del 1 marzo; ciò che cambia è la risposta stessa, nel giorno stesso, e durante eventuali finestre di brownout pianificate prima di allora.

Un brownout cambia cosa dice l’header?

Il valore dell’header non deve necessariamente spostarsi per un brownout pianificato: la data di sunset resta la data di sunset, che la risorsa fallisca in modo intermittente prima o no. Ciò che cambia è la risposta, non l’header. Pianificare brevi finestre di 410 Gone nelle settimane prima della data annunciata, come descrive Deprecazione API, è ciò che trasforma il primo contatto di chi chiama con il guasto in una prova generale invece che nell’evento reale il giorno in cui arriva la data dell’header.

FAQ

Client o strumenti HTTP reali leggono davvero l’header Sunset? Raramente, lato client. Il suo valore è soprattutto per chi gestisce l’infrastruttura tra voi e chi chiama: un API gateway o uno strumento di monitoraggio che configurate per osservare l’header può avvisare il vostro team, o quello di un partner, molto prima che il codice di chi chiama se ne accorga mai. Trattatelo come un segnale attorno a cui costruire strumenti, non uno che potete dare per scontato che l’altra parte abbia già.

Sunset è la stessa cosa di Cache-Control: max-age? No. max-age riguarda per quanto tempo resta valida una copia in cache; Sunset riguarda quando la risorsa smette del tutto di esistere. Una risposta può avere un max-age breve e una data Sunset lontana anni, o il contrario, e nessuno dei due header vincola l’altro.

Posso inviare Sunset per un singolo campo che sparisce, non per l’intero endpoint? No, l’header ha come ambito la risorsa, cioè l’URL, non un campo dentro il corpo della risposta. Per un campo, un parametro o un valore enum che sparisce mentre l’endpoint stesso resta attivo, usate invece l’header Deprecation e una voce di changelog; Deprecazione API copre esattamente come annunciare quel tipo di cambiamento.

E se la data di sunset deve essere spostata? Aggiornate il valore dell’header e ditelo nella voce di changelog che l’aveva annunciata la prima volta; cambiare silenziosamente una data pubblicata è il modo in cui chi chiama decide che nessuna delle vostre date è reale. La RFC descrive il valore come un suggerimento proprio perché le date a volte si spostano, ma una data spostata senza spiegazione vi costa anche la prossima.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Documentazione per sviluppatori, Esempi di changelog