Come scrivere una guida di migrazione per API

Una guida di migrazione API è il documento che trasforma un cambiamento incompatibile in una checklist invece che in un’interruzione: cosa è cambiato, cosa fare al riguardo, ed entro quando. Una voce di changelog può nominare un cambiamento incompatibile in due frasi; una guida di migrazione è ciò che chi chiama apre davvero quando quelle due frasi dicono “questo ti rompe” e ha bisogno di sapere esattamente cosa modificare. Pubblicare la voce senza la guida è come chi chiama scopre un cambiamento incompatibile da un ticket di supporto invece che dal documento scritto per prevenirlo.

Cos’è una guida di migrazione API?

Un documento passo passo che porta chi chiama dalla vecchia forma di un’API alla nuova, scritto per chi ha codice da modificare, non per chi sta decidendo se adottare l’API. Questa distinzione conta: una guida di migrazione presuppone un’integrazione esistente e traffico di produzione esistente, quindi deve coprire il rollback, la migrazione parziale, e come capire se la migrazione è riuscita, nulla di ciò che serve a una guida per una prima integrazione.

Una guida di migrazione si colloca di solito tra gli ultimi due: un avviso di deprecazione fa partire un conto alla rovescia, e la guida di migrazione è ciò che chi chiama segue prima che quel conto scada.

Quando un cambiamento ha bisogno di una guida di migrazione, e non solo di una voce di changelog?

Quando c’è più di un passaggio tra il vecchio comportamento e il nuovo, o quando il cambiamento tocca abbastanza punti di chiamata che chi chiama trae beneficio da un esempio lavorato più che da una descrizione. Cos’è un cambiamento incompatibile, e come rilasciarlo copre il test per stabilire se un cambiamento è incompatibile; se la risposta è sì, la seconda domanda è se la correzione è una modifica di una riga o una vera migrazione. Un campo rinominato può gestirlo chi chiama solo con la voce di changelog. Un cambiamento all’autenticazione, alla paginazione o alla gestione degli errori si guadagna quasi sempre una guida, perché il codice di sostituzione corretto non è ovvio da una descrizione di una frase.

Cosa deve contenere una guida di migrazione?

Cinque cose, e saltarne anche una sola è ciò che trasforma una guida in una pagina che chi chiama legge una volta e poi abbandona per procedere per tentativi. Il codice vecchio, mostrato così come apparirebbe davvero in un progetto. Il codice nuovo, mostrato allo stesso modo, non come descrizione astratta della differenza. Cosa si rompe se non si cambia nulla, detto chiaramente, perché “nulla” è una risposta valida e comune che chi chiama deve comunque sentirsi dire esplicitamente. Un modo per verificare che la migrazione abbia funzionato, come un campo di risposta o un codice di stato da controllare. E una tempistica: quando il vecchio comportamento smette di funzionare, e se entrambe le forme sono disponibili nel frattempo.

## Migrazione dei campi valuta da float a intero (v3.0.0)

Prima:
  { "amount": 19.99 }

Dopo:
  { "amount": 1999 }  // unità di valuta più piccola (centesimi)

Cosa cambia: `amount` è ora un intero nell'unità più piccola della
valuta dell'account. Il codice che legge `amount` come float leggerà
un valore 100 volte troppo grande a partire dal 1 ottobre 2026.

Verifica: dopo la migrazione, un addebito di 19,99 dovrebbe leggersi
come `amount: 1999`, non come `amount: 19.99`.

Tempistica: v2 continua a restituire float fino al 15 gennaio 2027.
v3 restituisce interi dal lancio. Entrambe le versioni sono attive ora.

Ognuna di queste cinque cose risponde a una domanda che chi chiama dovrebbe altrimenti indovinare o chiedere al supporto, ed è proprio quello il costo reale che una guida di migrazione fa risparmiare.

Chi dovrebbe scriverla, e quando?

Chi ha progettato il cambiamento, nello stesso momento in cui viene rilasciato, non un team di supporto che la ricostruisce dai ticket in seguito. Chi ha preso la decisione sa su quali parti del vecchio comportamento nessuno avrebbe dovuto fare affidamento e quali erano un contratto accidentale; una guida scritta più tardi da qualcuno senza quel contesto tende o a spiegare troppo l’ovvio o a perdere l’unico caso limite che rompe davvero le persone. La guida e la voce di changelog che annuncia il cambiamento incompatibile dovrebbero uscire insieme, con la voce che rimanda alla guida invece di ripeterla.

Come si collega questo al versionamento e al changelog API?

Direttamente: una guida di migrazione è la versione dettagliata di ciò che una voce MAJOR in semantic versioning e il tuo changelog riassume solo in una frase. La voce di changelog dice che un cambiamento è incompatibile e a grandi linee cosa è cambiato; la guida di migrazione è il link che quella voce dovrebbe portare. Changelog di API: cosa pubblicare e chi lo legge elenca la guida di migrazione come uno dei cinque documenti che un’API mantiene, ognuno risponde a una domanda diversa; questa è quella che risponde “come passo davvero da A a B”, e si guadagna una pagina tutta sua proprio perché quella risposta di solito è troppo lunga per una voce di changelog.

Per quanto tempo dovrebbe restare pubblicata una guida di migrazione?

Almeno finché il vecchio comportamento resta raggiungibile, e idealmente anche dopo. Chi migra con diciotto mesi di ritardo, dopo aver ignorato tre avvisi di deprecazione, ha comunque bisogno della guida, e cancellarla il giorno in cui il vecchio comportamento viene spento garantisce solo che chi ne ha più bisogno non la trovi. Tienila a un URL stabile e aggiorna la sezione tempistica invece di ritirare la pagina. La guida di upgrade di Stripe è un esempio pubblico di questo schema: una pagina sola, mantenuta aggiornata release dopo release, invece di un documento nuovo per ogni versione che diventa vecchio nel momento in cui esce la successiva. La vostra guida merita un posto altrettanto trovabile, accanto alla documentazione che chi chiama sta già leggendo, invece che sepolta in un archivio del blog.

FAQ

Ogni cambiamento incompatibile ha bisogno di una guida di migrazione? No. Un cambiamento che chi chiama può risolvere solo con la voce di changelog, come un singolo campo rinominato con un sostituto ovvio, non ha bisogno di una guida separata. Un cambiamento che tocca più punti di chiamata o richiede un esempio lavorato, sì.

Una guida di migrazione dovrebbe stare con la documentazione API o nel changelog? Con la documentazione, collegata dalla voce di changelog. La voce è ciò che una lettrice vede per prima; la guida è ciò di cui ha bisogno una volta deciso di agire, e appartiene accanto al materiale di riferimento che chi chiama sta già usando.

Qual è la differenza tra una guida di migrazione e un avviso di deprecazione? Un avviso di deprecazione dichiara che qualcosa sta per sparire ed entro quando. Una guida di migrazione sono le istruzioni su cosa fare al riguardo. Un avviso di deprecazione senza guida di migrazione collegata dice a chi chiama una scadenza senza dirle come rispettarla.

Il vecchio e il nuovo comportamento andrebbero entrambi documentati durante una finestra di migrazione? Sì, sulla stessa pagina se possibile, così chi chiama vede esattamente cosa è cambiato invece di ricostruirlo da due documenti separati scritti in momenti diversi.

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