Versionare le API senza rompere i client

Le API cambiano, i client no

Un'API di successo viene integrata da molti client che non puoi aggiornare a comando. Quando l'interfaccia evolve, serve una strategia di versioning che permetta di introdurre modifiche senza spezzare le integrazioni esistenti.

Le strategie principali

Esistono tre approcci ricorrenti, ognuno con compromessi diversi:

• Versioning nell'URI: /v1/ordini, /v2/ordini. Esplicito e facile da leggere, ma mescola la versione con la risorsa.
• Header personalizzato: il client invia X-API-Version: 2. Mantiene gli URL puliti ma e meno visibile.
• Media type (content negotiation): Accept: application/vnd.azienda.v2+json. Elegante e conforme a REST, ma piu complesso da usare e testare.

Cambiamenti compatibili e non

La distinzione chiave e tra modifiche retrocompatibili e breaking change. Aggiungere un campo opzionale a una risposta e sicuro; rimuovere un campo, rinominarlo o cambiarne il tipo no.

GET /v2/ordini/42 HTTP/1.1
Accept: application/json
X-API-Version: 2

Gestire la transizione

Una buona evoluzione mantiene la versione precedente attiva per un periodo di deprecazione annunciato, documenta i cambiamenti e usa header come Deprecation e Sunset per avvisare i client. Cosi i consumatori hanno il tempo di adeguarsi.

In MUSTNODE SRL progettiamo le API con il versioning fin dall'inizio, perche un contratto stabile e cio che permette alle integrazioni dei nostri clienti di durare nel tempo.