Changelog di API: cosa pubblicare e chi lo legge

Un changelog di API è il registro datato di ogni cambiamento che un chiamante potrebbe notare, scritto per chi integra con l’API, non per il team che la rilascia. Questo pubblico lo rende un documento diverso da un changelog di prodotto: chi legge sta decidendo se il proprio codice funzionerà ancora il mese prossimo. La maggior parte fallisce nello stesso modo, essendo una copia filtrata di un feed interno di release, così un campo rimosso finisce accanto a una correzione di testo con lo stesso peso, e nessuno dei due viene letto.

Cos’è un changelog di API?

È il registro pubblico e datato dei cambiamenti a un’interfaccia contro cui altre persone hanno scritto codice. Il test utile per stabilire se qualcosa vi appartiene non ha nulla a che fare con quanto fosse grande il cambiamento internamente. Chiede se un chiamante corretto, scritto l’anno scorso e mai toccato da allora, potrebbe comportarsi diversamente a causa sua. Questo test ammette alcuni cambiamenti molto piccoli ed esclude alcuni molto grandi.

Tutto quello che segue presuppone che chi chiama sia fuori dall’azienda e sostanzialmente irraggiungibile se non tramite questo documento. Quando chi chiama è un altro team della stessa azienda, il calcolo cambia abbastanza da richiedere un trattamento proprio; changelog di API interna copre cosa serve invece a quel pubblico.

Come scrivere una guida di migrazione per API copre per intero quest’ultimo documento; in breve è ciò a cui una voce di cambiamento incompatibile dovrebbe rimandare invece di provare a sostituirlo.

I cinque sono documenti separati con cicli di vita separati. Un avviso di deprecazione è una promessa con una data, e appartiene anche al changelog, ma una voce di changelog si scrive una volta sola mentre una deprecazione si segue fino al suo sunset. Confonderli è il motivo per cui i sunset vengono persi.

Cosa appartiene a una singola voce?

Sei cose, e le prime tre sono quelle che di solito mancano. Il cambiamento, espresso in termini di richiesta o risposta piuttosto che del componente interno. Se rompe un chiamante corretto. Cosa deve fare il chiamante, incluso “niente”. La data in cui è entrato in vigore. La versione o le versioni coinvolte. Un link alla guida di migrazione, quando esiste.

Una voce che dice “migliorato l’endpoint account” fallisce su tutte e sei. Una voce che dice “il campo accounts.type ora restituisce individual dove prima restituiva personal; i valori esistenti restano invariati per gli account creati prima del 2 settembre; nessuna azione richiesta a meno che tu non confronti la stringa” risponde a tutte e sei in una frase.

Categorizzate le voci per conseguenza, non per reparto. Tre etichette portano quasi tutto il valore: breaking, additive e fixed. Semantic Versioning definisce già le prime due con precisione, e prendere in prestito le sue definizioni invece di inventarne di locali significa che chi conosce semver conosce le vostre etichette. Keep a Changelog ne offre un set più lungo se lo volete, e la sua regola centrale vale qui più che altrove: il log è per gli esseri umani, e un dump di titoli di commit non lo è.

In cosa un changelog di API differisce dalle note di rilascio?

Le note di rilascio descrivono cosa può fare ora il prodotto. Un changelog di API descrive qual è ora il contratto. Lo stesso lavoro rilasciato produce spesso una voce in entrambi, formulata in modo diverso, perché i pubblici hanno bisogno di cose diverse: un nuovo formato di esportazione è una funzione per un utente e un nuovo valore enum per un chiamante che dipende da quel campo.

La conseguenza pratica è che i due non possono essere lo stesso feed con stile diverso. Un chiamante che si iscrive a tutto quello che rilasciate finirà per disiscriversi, e allora perderà il breaking change. Se pubblicate un feed, filtratelo; se ne pubblicate due, rendete quello API più stretto e non lasciateci mai entrare una voce di marketing. Confrontiamo entrambe le forme fianco a fianco in changelog vs note di rilascio.

Dove dovrebbe vivere un changelog di API?

Accanto alla documentazione di riferimento, su una URL stabile, con ogni voce indirizzabile singolarmente tramite un frammento o un proprio percorso. I chiamanti collegano le voci nelle revisioni degli incidenti e nei ticket interni, e una voce che non si può collegare finisce incollata come screenshot al suo posto.

Pubblicatelo anche come output leggibile dalla macchina, oltre che come pagina. Un feed JSON che segue la specifica JSON Feed o un feed RSS non costa nulla una volta che le voci sono dati strutturati, ed è ciò che permette a un cliente di inserire i vostri cambiamenti nel proprio processo di release. Questo decide anche se qualcuno ci costruisce sopra. GitHub documenta le sue versioni della REST API accanto al riferimento per lo stesso motivo: la politica delle versioni fa parte dell’interfaccia.

Come si presenta una buona voce nella pratica?

Tre voci della stessa settimana, nella forma descritta sopra:

2026-09-02  Breaking  v2
  `POST /invoices` ora rifiuta una `currency` che non corrisponde alla
  valuta dell'account del cliente, restituendo 422 invece di convertire
  silenziosamente. I chiamanti che facevano affidamento sulla conversione
  devono inviare la valuta dell'account. Riguarda solo v2; v1 resta
  invariata fino al sunset del 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` guadagna un timestamp `settled_at`, null finché la fattura
  non viene saldata. Nessuna azione richiesta. I client che rifiutano
  campi sconosciuti dovrebbero essere aggiornati.

2026-08-31  Fixed  v2
  `GET /invoices?status=` restituiva una pagina vuota invece di un 400
  per uno stato sconosciuto. Ora restituisce 400 con i valori accettati.
  I chiamanti con un errore di battitura prima non vedevano risultati,
  ora vedono un errore.

La terza è il tipo più spesso omesso, perché internamente è una correzione di bug. Per un chiamante che ha costruito un retry intorno a quella pagina vuota, è un cambiamento di comportamento, e la voce è ciò che evita il ticket di supporto. L’etichetta dice fixed e il corpo dice cosa un chiamante potrebbe notare, che è la distinzione che mantiene onesto il log senza gonfiare ogni correzione a breaking change.

Come si iscrivono i chiamanti?

Dategli più di un canale, perché hanno lavori diversi. Un feed per lo sviluppatore che vuole tutto. Email per chi vuole solo i breaking change. Header di risposta per il codice stesso, l’unico iscritto che non dimentica mai di controllare: l’header Sunset definito in RFC 8594 mette la data di ritiro nella risposta, dove una libreria client può registrarla.

Il canale che la maggior parte dei team salta è quello diretto. Se un chiamante ha usato la scorsa settimana il campo che state cambiando, sapete chi è, e una email a quegli account vale più di qualsiasi quantità di broadcast. È la stessa disciplina del chiudere il ciclo di feedback del cliente, applicata a un cambiamento che nessuno ha richiesto: le persone coinvolte vengono avvisate individualmente, e a tutti gli altri arriva il feed. Un webhook è un quarto canale con una propria modalità di fallimento da conoscere prima di farci affidamento: i changelog dei webhook copre perché un cambiamento di payload lì si rompe in silenzio, senza chiamante che possa rifiutare la nuova forma.

Come si scrive una voce per un breaking change?

Iniziate con la rottura, non con il motivo. Un chiamante che scorre dieci voci deve sapere nella prima frase se questa gli costerà lavoro. Poi la data, le versioni coinvolte, la migrazione, e la scadenza se il vecchio comportamento sta per sparire invece di cambiare.

Mettete lo stesso contenuto nell’avviso di deprecazione, nell’header di risposta e nell’email diretta, formulato in modo coerente, e date a tutti e quattro la stessa data. La divergenza tra loro è l’errore che trasforma un cambiamento pianificato in un incidente, perché il chiamante che ne ha letto solo uno agisce sulla data sbagliata. Cos’è un breaking change copre la decisione in sé, e come deprecare un’API copre il calendario che segue.

In changeloop, un cambiamento di API diventa una voce quando la pull request viene fusa, una persona modifica e approva la bozza, e la voce viene pubblicata su feed e widget nello stesso momento in cui un chiamante il cui feedback dal widget è diventato l’issue GitHub chiusa dalla pull request viene avvisato su quell’issue. Il passo di revisione è quello che conta qui: un changelog di API è un documento contrattuale, e nessuna bozza dovrebbe raggiungere un chiamante senza che una persona l’abbia letta.

FAQ

Ogni cambiamento di API ha bisogno di una voce nel changelog? Ogni cambiamento che un chiamante corretto potrebbe notare sì, inclusi quelli che considerate interni. I cambiamenti senza effetto osservabile sulla richiesta o sulla risposta no, e aggiungerli allena i lettori a scorrere senza leggere.

Il changelog di API dovrebbe vivere nei docs o sul sito di marketing? Nei docs, accanto al riferimento. Chi legge di solito è già lì, e un changelog sul sito di marketing tende ad acquisire un pubblico per cui non è stato scritto.

Fino a quando dovrebbe risalire? Indefinitamente. Le voci vengono citate anni dopo nelle revisioni degli incidenti, e un log troncato rompe quei link. Paginare invece di potare.

Serve un changelog separato per ogni versione di API? No, un unico log con un campo versione per voce è più facile da leggere e da cercare. Filtrare per versione è una funzione della pagina, non un motivo per dividere il documento.

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