# Un header HTTP standard per dire che un'API è deprecata (RFC 9745)
Table of Contents
Chi mantiene un’API si trova prima o poi a dover ritirare qualcosa: un indirizzo che risponde da anni, un formato di risposta, un’intera versione del servizio. Il problema non è tecnico, è di comunicazione. Come si avvisa chi usa quell’API che sta per sparire, senza sperare che qualcuno legga la mail giusta o la nota giusta nel changelog? A marzo 2025 l’IETF, l’organismo che cura gli standard tecnici di Internet, ha pubblicato la RFC 9745 e ha reso standard un modo semplice per dirlo dentro le risposte stesse: l’intestazione HTTP Deprecation, uno dei tanti aggiornamenti con cui l’IETF sta ampliando il protocollo, insieme per esempio al nuovo metodo HTTP QUERY.
Il problema: avvisare le macchine, non solo le persone
Prima un po’ di vocabolario, perché serve. Un’API è l’interfaccia con cui due programmi si parlano via rete. Un endpoint è uno degli indirizzi che quell’API espone. Un’intestazione (in inglese header) è una riga di informazioni di servizio che accompagna ogni richiesta e ogni risposta HTTP, separata dal contenuto vero e proprio. E deprecare una risorsa significa dichiararla ancora funzionante ma in via di dismissione: si può usare, ma conviene smettere e passare ad altro.
Fin qui la deprecazione si annuncia quasi sempre a parole: un post sul blog, una voce nella documentazione, un’email agli sviluppatori. Va bene per le persone, ma non per il software. Un programma che chiama un’API mille volte al giorno non legge il blog. Continua a chiamare quell’endpoint finché un giorno smette di rispondere, e a quel punto è un guasto in produzione. Manca un modo perché sia la risposta stessa a dire, in forma leggibile da un computer: “attenzione, questa risorsa è in via di dismissione”.
È esattamente il vuoto che la RFC 9745 vuole colmare.
Cos’è la RFC 9745
La RFC 9745 si intitola The Deprecation HTTP Response Header Field ed è stata pubblicata nel marzo 2025 dall’IETF, con Sanjay Dalal ed Erik Wilde come autori. Definisce una nuova intestazione di risposta, Deprecation, con cui un server segnala a chi usa una risorsa che quella risorsa sarà o è già stata deprecata.
Il meccanismo è volutamente minimale. Il server aggiunge una riga alle proprie risposte HTTP e chi le riceve - un client, uno strumento di monitoraggio, una libreria - può leggerla in automatico. Nessun cambiamento al contenuto, nessuna rottura: solo un segnale in più.
Come si scrive: una data, e basta
Il valore dell’intestazione è una data, espressa nel formato dei Structured Fields di HTTP (RFC 9651), lo standard che definisce come scrivere valori strutturati dentro le intestazioni in modo che tutti li interpretino allo stesso modo. In pratica la data si scrive come un timestamp Unix - cioè il numero di secondi trascorsi dal 1° gennaio 1970 - preceduto da una chiocciola. Un esempio dalla specifica:
Deprecation: @1688169599Quel numero corrisponde al 30 giugno 2023 alle 23:59:59 UTC. La cosa interessante è che la data può stare nel futuro o nel passato. Nel futuro significa “questa risorsa verrà deprecata a partire da quel momento”: un preavviso. Nel passato significa “è già deprecata da allora”. Con una sola riga il server comunica sia l’intenzione sia il fatto compiuto.
Deprecato non vuol dire spento
Qui va chiarito un equivoco frequente, e la RFC è esplicita. Deprecare non cambia il comportamento della risorsa. Un endpoint deprecato continua a funzionare come prima: risponde, restituisce gli stessi dati, non cambia significato. La presenza dell’intestazione non è un errore e non impone di smettere di usarlo da subito. È un avviso, non una porta chiusa.
Deprecazione e dismissione sono due momenti distinti. La deprecazione dice “inizia a spostarti”; la dismissione (in inglese sunset) è il giorno in cui la risorsa smetterà davvero di rispondere. Tra i due c’è, o dovrebbe esserci, il tempo per migrare.
Il compagno naturale: l’intestazione Sunset
Proprio per indicare quel giorno esiste un’altra intestazione standard, Sunset, definita dalla RFC 8594. Mentre Deprecation dice “da quando è deprecata”, Sunset dice “da quando smetterà di funzionare”. Le due si usano bene insieme, e la RFC 9745 mette un vincolo di buon senso: la data di Sunset non può essere precedente a quella di Deprecation. Non avrebbe senso spegnere una risorsa prima ancora di averla dichiarata in dismissione.
Dire cosa usare al posto suo: la relazione “deprecation”
Una data, da sola, non dice tutto. Non spiega perché la risorsa viene ritirata, cosa usare in alternativa, entro quando completare il passaggio. Per questo la RFC 9745 definisce anche una link relation chiamata deprecation: un modo standard per collegare, sempre via intestazione, una pagina di documentazione dove sta il resto della storia. L’esempio della specifica è questo:
Deprecation: @1688169599Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"L’intestazione Link punta a un indirizzo, e rel="deprecation" dichiara che quel collegamento parla proprio della dismissione. Lì il fornitore dell’API può descrivere la politica di deprecazione, la tempistica e - quando esiste - la risorsa che prende il posto di quella vecchia, con una guida alla migrazione. La documentazione può anche fissare una regola chiara, per esempio che ogni deprecazione verrà annunciata con un certo numero di giorni di anticipo rispetto alla data di spegnimento.
Perché conta nel ciclo di vita di un’API
Il valore di tutto questo non è l’intestazione in sé, ma il fatto che finalmente un avviso di dismissione sia leggibile dalle macchine, lo stesso principio dietro ad altri segnali HTTP pensati per i client automatici, come quello che permette di far pagare i crawler AI. Cambia diverse cose pratiche.
- Un client può accorgersi da solo di star chiamando un endpoint deprecato e scriverlo nei propri log, invece di scoprirlo il giorno in cui l’endpoint muore.
- Uno strumento di monitoraggio può controllare le risposte e far scattare un avviso quando compare l’intestazione, dando al team il tempo di reagire.
- Chi consuma decine di API diverse può misurare quanto “debito” ha accumulato, cioè quante dipendenze stanno per sparire, senza inseguire changelog scritti in modi diversi da ogni fornitore.
In una parola, la gestione del ciclo di vita di un’API smette di dipendere dal fatto che una persona abbia letto la comunicazione giusta al momento giusto. Il segnale viaggia insieme ai dati.
A che punto è
Un chiarimento sullo stato, perché è facile fraintenderlo. La RFC 9745 è uno Standard Proposto (Proposed Standard): non è una bozza né un documento sperimentale, ma il primo gradino stabile della via degli standard IETF, lo stesso livello raggiunto anche dallo schema di autenticazione HTTP Concealed. Significa che il testo è maturo, rivisto pubblicamente e citabile, e che l’intestazione Deprecation è stata registrata in modo permanente nel registro ufficiale dei nomi di campo HTTP. Da qui in avanti chi progetta API può adottarla sapendo che il significato è fissato una volta per tutte.
Resta il lavoro di adozione, che dipende dai singoli fornitori: il valore dell’intestazione si vede solo quando i server la inviano e i client la leggono. Ma la parte difficile - mettersi d’accordo su un formato unico e sensato - è fatta. Per chi mantiene API, aggiungere un’intestazione Deprecation (e possibilmente una Sunset e un link alla documentazione) è un gesto piccolo che rende una dismissione molto meno traumatica per chi sta dall’altra parte.
