Le API si evolvono. Nuove funzionalità, correzioni, deprecazioni. Ma i client dipendono dall'interfaccia corrente. Il controllo delle versioni consente l'evoluzione senza interrompere le applicazioni esistenti. Questa guida presenta strategie e migliori pratiche.
Perché la versione
Compatibilità
I vecchi clienti continuano a lavorare.
Evoluzione
Migliora senza bloccarti.
Documentazione
Chiarezza su cosa aspettarsi.
Transizione
È tempo che i clienti migrano.
Quando eseguire la versione
Modifiche importanti
Cambiamenti che rompono i contratti.
Esempi
- Rimuovi campo
- Cambia il tipo di dati
- Cambia significato
- Rimuovere l'endpoint
Non eseguire la versione per
Aggiunte, che sono generalmente compatibili.
Strategie di controllo delle versioni
###PercorsoURL
/api/v1/utenti, /api/v2/utenti.
Parametro di query
/api/users?versione=1.
Intestazione
Accept-Version: v1 o API-Version: 2.
Negoziazione dei contenuti
Accept: application/vnd.myapi.v1+json.
Controllo delle versioni del percorso URL
Vantaggi
Visibile, chiaro, facile da instradare.
Svantaggi
Gli URL cambiano con la versione.
Esempio
OTTIENI /api/v1/prodotti OTTIENI /api/v2/prodotti
Comune
Approccio più popolare.
Controllo delle versioni dell'intestazione
Vantaggi
URL puliti e semanticamente corretti.
Svantaggi
Meno visibile, più difficile da testare.
Esempio
OTTIENI /api/prodotti Intestazione: Versione API: 2
Versionamento semantico
Formato
PATCH.MAGGIORE.MINORE.
MAGGIORE
Cambiamenti decisivi.
MINORE
Aggiunte compatibili.
PATCH
Bug fantastici.
Per le API
Generalmente solo MAJOR nella versione pubblica.
Deprecazione
Processo
Contrassegna come deprecato prima di rimuoverlo.
Comunicazione
Intestazioni, documentazione, registro delle modifiche.
Cronologia
Scadenza della migrazione.
Supporto
Per quanto tempo rimanere deprecato.
Intestazioni del tramonto
Intestazione HTTP
Sunset: Sat, 01 Jul 2024 00:00:00 GMT.
Intestazione di deprecazione
Indica che è deprecato.
Comunicazione
I client possono rilevare automaticamente.
Migrazione
Documentazione
Cosa è cambiato, come adattarsi.
Guide
La migrazione passo dopo passo.
Supporto
Aiuto durante la transizione.
Cronologia
Termine ragionevole.
Compatibilità con le versioni precedenti
Obiettivo
Nuovi client, vecchie API funzionano.
Additivo
Aggiungi, non rimuovere.
Valori predefiniti
Nuovi campi con valori predefiniti.
###Facoltativo
Nuovi parametri opzionali.
Compatibilità futura
Concetto
Vecchi clienti con nuove API.
Ignora Sconosciuto
Ignora i campi sconosciuti.
Degradazione aggraziata
Lavora senza nuove funzionalità.
Progettare per l'evoluzione
Estendibilità
Pensa ai cambiamenti futuri.
Strutture generiche
Oggetti estensibili.
Flag di funzionalità
Non esporre funzionalità incomplete.
Contratti
Definisci chiaramente ciò che prometti.
Versioni multiple
Manutenzione
Costo per mantenerne diversi.
Limiti
Quanti supportarne contemporaneamente.
Politica
Stabilisci regole chiare.
Documentazione
Per versione
Documenti specifici della versione.
Registro delle modifiche
Cosa è cambiato tra le versioni.
Guide alla migrazione
Come aggiornare.
Avvisi di deprecazione
Cosa verrà fuori.
Strumenti
OpenAPI/Swagger
Specifica con versione.
Postino
Raccolte per versione.
Gateway API
Instradamento della versione.
Errori comuni
Versione eccessiva
Nuova versione per ogni modifica.
Non eseguire la versione
Modifica decisiva senza una nuova versione.
Deprecato velocemente
Non concedere tempo per la migrazione.
Nessuna comunicazione
Clienti sorpresi dai cambiamenti.
SDK e client
Versioni corrispondenti
SDK v1 per API v1.
Manutenzione
Mantieni aggiornati gli SDK.
Comunicazione
Notifica sulle nuove versioni.
Conclusione
Il controllo delle versioni API è una disciplina a lungo termine. Scegli una strategia chiara, comunica i cambiamenti e concediti il tempo per la migrazione. Il risultato sono API che si evolvono senza interrompere le integrazioni.
##Domande frequenti
1) Quale strategia di controllo delle versioni utilizzare? Il percorso URL è il più comune e consigliato per la maggior parte.
2) Quando aumentare la versione principale? Per modifiche di rilievo che non sono compatibili con le versioni precedenti.
3) Per quanto tempo sarà supportata la vecchia versione? 6-12 mesi è comune. Dipende dai clienti.
4) Posso apportare modifiche senza controllo delle versioni? Aggiunte generalmente sì. Nessuna rimozione/modifica.
5) Come segnalare il ritiro? Intestazioni, documenti, email, periodo di transizione.
Leggi anche
- GraphQL per applicazioni: Guida all'implementazione
- Backend per applicazioni: architettura, tecnologie e best practice
- Microservizi nelle applicazioni: architettura distribuita per dispositivi mobili
- API per applicazioni
- API per applicazioni - Passo dopo passo nella vita di tutti i giorni
- API per applicazioni: scalabilità passo dopo passo