API Versioning: come far evolvere un’API senza compromettere le integrazioni esistenti?

Un’API può iniziare con una funzione relativamente semplice: un’applicazione richiede dei dati e un altro sistema li fornisce.

Con il tempo, però, le cose cambiano. Vengono aggiunti nuovi campi, la struttura dei dati evolve, le funzionalità migliorano e nascono nuove esigenze.

Ma c’è una difficoltà: l’API può essere cambiata, mentre i sistemi che la utilizzano non sono ancora stati aggiornati.

Quando più applicazioni, piattaforme o servizi sono integrati con la stessa API, una modifica apparentemente minima può avere un impatto su più sistemi contemporaneamente.

È qui che entra in gioco l’API Versioning.

Quando una piccola modifica coinvolge più sistemi

Prendiamo un esempio semplice.

Un’API restituisce le informazioni di un cliente, come nome, indirizzo e numero di telefono. In seguito, la struttura deve cambiare perché il sistema richiede un modo diverso di organizzare i dati relativi agli indirizzi.

Per una nuova applicazione, questa modifica può rappresentare un miglioramento. Un’applicazione esistente, invece, potrebbe aspettarsi ancora la struttura precedente.

Se l’API viene modificata direttamente, l’integrazione esistente potrebbe non funzionare più come previsto.

Per questo, nello sviluppo delle API non basta pensare alle nuove funzionalità. È necessario considerare anche i sistemi che dipendono dal comportamento attuale dell’API.

Una nuova versione può coesistere con quella attuale

L’API Versioning offre un modo controllato per gestire questo cambiamento.

Invece di sostituire immediatamente la versione esistente, è possibile introdurne una nuova. Ad esempio, i sistemi esistenti possono continuare a utilizzare v1, mentre le nuove integrazioni o quelle già aggiornate passano a v2.

In questo modo, il cambiamento non deve avvenire contemporaneamente in tutto l’ecosistema.

I team hanno il tempo necessario per adattare le integrazioni, testare la nuova versione e pianificare gradualmente la transizione. La versione precedente può continuare a essere supportata per un periodo definito ed essere dismessa solo quando i sistemi che ne dipendono sono pronti.

Non ogni modifica richiede una nuova versione

API Versioning non significa che ogni miglioramento debba necessariamente portare a v2, v3 o v4.

Molte modifiche possono essere introdotte mantenendo la retrocompatibilità, senza alterare il modo in cui i sistemi esistenti comunicano con l’API.

Una nuova versione diventa necessaria quando una modifica non può essere introdotta senza cambiare il contratto esistente dell’API.

Per questo il versioning non è semplicemente una convenzione di denominazione. Fa parte del modo in cui viene progettata e gestita l’evoluzione di un’integrazione.

Un’API deve essere progettata anche per evolvere

Per un’azienda di sviluppo software, una buona integrazione non consiste semplicemente nel collegare due sistemi che devono comunicare oggi.

I sistemi cambieranno. Le applicazioni verranno aggiornate. Le esigenze di business evolveranno.

L’architettura deve quindi prevedere questi cambiamenti, evitando che ogni aggiornamento diventi un problema per gli altri sistemi.

Come spiega Ermal Beqiri, fondatore di ALSoft:

“Un’API ben progettata deve consentire al sistema di evolvere, continuando al tempo stesso a garantire il funzionamento delle integrazioni esistenti e una transizione controllata verso i nuovi cambiamenti.”

L’API Versioning non riguarda semplicemente la gestione delle versioni, ma la creazione di integrazioni capaci di evolvere senza compromettere il funzionamento dei sistemi esistenti.