Gestione del ciclo di vita delle API

Questa pagina descrive le funzionalità di controllo delle versioni dell'API Cloud Endpoints e fornisce le best practice per il controllo delle versioni e la gestione temporanea dell'API Endpoints. Le informazioni in questa pagina si applicano alle API che utilizzano la specifica OpenAPI. Per le API che utilizzano i framework Cloud Endpoints per l'ambiente standard App Engine, consulta Gestione del controllo delle versioni delle API: Java o Gestione del controllo delle versioni delle API: Python.

Ti consigliamo di seguire gli stessi principi di base utilizzati da Google per il controllo delle versioni delle API e la gestione temporanea dei servizi:

  • Includi quanto segue nel file di configurazione OpenAPI prima di eseguire il deployment della versione iniziale:

    • Imposta il numero di versione nel campo info.version. Ti consigliamo di utilizzare una stringa di versione che includa una versione principale e una versione secondaria, ad esempio 1.0.
    • Imposta il campo basePath in modo da includere il numero di versione principale. Ti consigliamo di utilizzare un percorso di base formattato con la lettera v seguita dal numero di versione principale, ad esempio /v1.

  • Quando devi apportare una modifica compatibile con le versioni precedenti, ad esempio aggiungendo un nuovo metodo, incrementa il numero di versione secondaria (1.2, 1.3 e così via) nel campo info.version ed esegui nuovamente il deployment. Per i dettagli, consulta Controllo del controllo delle versioni di un'API.

  • Quando devi apportare una modifica a un metodo esistente che interrompe il codice client, crea una copia del file di configurazione OpenAPI e apporta le seguenti modifiche:

    • Incrementa il numero di versione principale (2.0, 3.0 e così via) nel campo info.version.
    • Incrementa il numero di versione principale (/v2, /v3 e così via) nel campo basePath.

    Esegui il deployment di entrambe le versioni dei file di configurazione OpenAPI ed esegui nuovamente il deployment del backend, che ora include entrambe le versioni del metodo. Per i dettagli, consulta Controllo del controllo delle versioni di un'API.

  • Implementa tutte le versioni principali delle API in un singolo backend. Questo consiglio:

    • Semplifica il routing perché le richieste a una versione specifica si basano sul percorso, come nell'esempio precedente.
    • Semplifica la configurazione e il deployment. Puoi utilizzare lo stesso progetto e backend Google Cloud per tutte le versioni principali dell'API ed eseguire il deployment di tutte le versioni dell'API contemporaneamente.
    • Tiene bassi i costi evitando di eseguire backend superflui.

  • Prepara l'API in un progetto Google Cloud separato prima di eseguirne il deployment nel progetto Google Cloud di produzione. Per i dettagli, consulta Servizi di gestione temporanea.

L'utilizzo dei numeri di versione principali e secondari in Endpoints corrisponde alle definizioni nel controllo delle versioni semantico. Sebbene Endpoints non richieda l'incremento del numero di versione della patch nel file di configurazione OpenAPI e l'esecuzione del deployment della configurazione quando esegui il deployment di una correzione di bug nel codice di backend, puoi scegliere di farlo se vuoi.

Funzionalità di controllo delle versioni dell'API Cloud Endpoints

Extensible Service Proxy (ESP) ha la possibilità di gestire più versioni principali dell'API contemporaneamente in un singolo progetto e backend Google Cloud, a condizione che le API non abbiano percorsi sovrapposti. Ad esempio:

http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo

Ciò consente ai clienti di scegliere la versione da utilizzare e controllare quando eseguono la migrazione alla nuova versione. L'ESP tagga ogni richiesta con il numero di versione prima di indirizzarla al metodo applicabile nel backend. Poiché ogni richiesta è codificata con un numero di versione:

  • I grafici e i log in Endpoint > Servizi mostrano le richieste di ogni versione principale dell'API e il totale aggregato di tutte le versioni. Puoi filtrare la visualizzazione per una versione specifica. Questo ti dà un'idea chiara di quanto traffico sta ricevendo ogni versione. I log possono anche indicare quali client stanno utilizzando la versione.

  • Quando esegui nuovamente il deployment dell'API con un aggiornamento del numero di versione secondario, l'attività successiva viene etichettata con il nuovo numero di versione nei grafici e nei log. In questo modo avrai una cronologia etichettata dei deployment.

  • Quando rimuovi una versione di un'API, i grafici e i log continuano a mostrare dati relativi all'intervallo di tempo in cui l'API era attiva.

Esempio di ciclo di vita delle API

Questa sezione descrive una tipica evoluzione di un servizio.

Versione 1

Inizialmente esegui il deployment della versione 1 del servizio API My Awesome Echo. L'API viene gestita da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Nei grafici e nei log in Endpoint > Servizi, vedrai tutto il traffico in 1.0.

Versione 1.1

I tuoi clienti richiedono una nuova funzionalità, quindi aggiungi un nuovo metodo. Nel file di configurazione OpenAPI, aggiungi il nuovo metodo e incrementa il campo info.version in 1.1. Aumenta il numero di versione secondaria perché questa modifica non compromette il codice client. Esegui il deployment e test delle modifiche in un ambiente di gestione temporanea per assicurarti che funzioni.

Successivamente, eseguirai il deployment della configurazione OpenAPI e del backend dell'API nell'ambiente di produzione. L'API viene ancora gestita da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, ma ora i chiamanti possono effettuare richieste al nuovo metodo. Poiché non hai cambiato l'interfaccia utilizzando i metodi precedenti, i clienti non devono modificare ed eseguire nuovamente il deployment dei propri client, i quali possono continuare a inviare richieste al metodo precedente come prima.

In Endpoint > Servizi, il traffico gestito è ora alla versione 1.1. Se selezioni un intervallo di tempo precedente da visualizzare, la versione precedente viene mostrata nei grafici e nei log, fornendo una cronologia etichettata dei deployment.

Versione 2.0

Nel tempo, ti rendi conto che è necessario apportare una modifica incompatibile con le versioni precedenti a un metodo esistente. Poiché è importante non danneggiare il codice client dei tuoi clienti, decidi di mantenere due versioni dell'API. Lascia invariato il vecchio metodo e implementa la nuova versione. Creerai un altro file di configurazione OpenAPI per la versione 2.0 e configurerai la nuova versione in modo che venga pubblicata da my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Il file di configurazione OpenAPI originale rimanda ancora alla versione precedente del metodo, mentre il nuovo file di configurazione OpenAPI rimanda alla nuova versione del metodo.

Esegui contemporaneamente il deployment dei file di configurazione OpenAPI di versione 1 e 2 ed esegui nuovamente il deployment del backend, che ora contiene entrambe le versioni del metodo. Per maggiori dettagli, consulta Controllo del controllo della versione di un'API.

Dopo il deployment, Endpoint > Servizi indica che stai gestendo due versioni dell'API e puoi vedere quanto traffico sta ricevendo ogni versione. I tuoi client v1 possono continuare a chiamare /v1, ma possono anche chiamare /v2 per utilizzare la nuova versione del metodo. La modalità di gestione del controllo delle versioni nel codice di backend dipende dal framework API in uso. Per un esempio di utilizzo dei servlet, consulta Esempio di endpoint e Java con più versioni.

Disabilitare la versione 1

Col tempo, man mano che la migrazione dei client effettuerai la migrazione di tutto il traffico alla v1, potrai interromperne la gestione. Per rimuovere la versione 1 dell'API, esegui solo il deployment del file di configurazione OpenAPI della versione 2 ed esegui nuovamente il deployment del backend. Ora puoi rimuovere in sicurezza dal tuo backend il codice che ha implementato la versione 1. Endpoint > Servizi conserva i dati storici della versione 1.x.

Servizi di gestione temporanea

Come best practice, ti consigliamo di aggiornare in modo graduale il servizio endpoint in modo da poter testare il servizio prima che raggiunga i clienti. Ti consigliamo inoltre di creare un progetto Google Cloud separato per la gestione temporanea del servizio, in modo che sia isolato dalla produzione. Ad esempio, le quote Google sono generalmente condivise dalle risorse all'interno di un progetto. Di conseguenza, se inserisci il servizio di gestione temporanea nello stesso progetto del servizio di produzione, un ciclo for errato, ad esempio, potrebbe causare un'interruzione del servizio di produzione.

Ti consigliamo di definire un nome per il progetto Google Cloud che indichi chiaramente che si tratta di un progetto gestione temporanea. Una strategia di denominazione comune consiste nell'utilizzare lo stesso nome del progetto Google Cloud di produzione, ma con -staging alla fine. Potresti anche voler inserire -prod nei progetti di produzione per chiarire che il progetto include i servizi di produzione.

I nomi dei servizi su Google Cloud devono essere univoci. Poiché specifichi il nome del servizio nel file di configurazione OpenAPI, devi mantenere file di configurazione API separati per i progetti di gestione temporanea e produzione oppure utilizzare un set di file di configurazione API e creare un processo in cui modificare il nome del servizio in modo che corrisponda a quello del progetto in cui stai eseguendo il deployment.

Passaggi successivi