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 lo staging dell'API Endpoints. Le informazioni riportate in questa pagina sono applicabili alle API che utilizzano la specifica OpenAPI. Per le API che utilizzano Cloud Endpoints Frameworks 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 lo staging dei servizi:

  • Prima di eseguire il deployment della versione iniziale, includi quanto segue nel file di configurazione OpenAPI:

    • 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 che includa il numero della versione principale. Ti consigliamo di utilizzare un percorso di base formattato come 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 informazioni dettagliate, consulta la sezione 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 e il redeployment del backend, che ora ha entrambe le versioni del metodo. Per informazioni dettagliate, consulta la sezione Controllo delle versioni di un'API.

  • Implementa tutte le versioni principali dell'API in un unico 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. Utilizzi lo stesso Google Cloud progetto e backend per tutte le versioni principali dell'API e implementi tutte le versioni dell'API contemporaneamente.
    • Mantiene bassi i costi evitando l'esecuzione di backend superflui.

  • Organizza l'API in un progetto Google Cloud separato prima di eseguire il deployment nel progetto Google Cloud di produzione. Per i dettagli, consulta Servizi di staging.

L'utilizzo dei numeri di versione principale e secondaria in Endpoints corrisponde alle definizioni riportate in Controllo delle versioni semantico. Anche se Endpoints non richiede di incrementare il numero di versione della patch nel file di configurazione OpenAPI e di eseguire il deployment della configurazione quando esegui il deployment di una correzione di bug nel codice backend, puoi scegliere di farlo se vuoi.

Funzionalità di controllo della versione dell'API Cloud Endpoints

Extensible Service Proxy (ESP) è in grado di gestire contemporaneamente più versioni principali della tua API in un unico Google Cloud progetto e backend, 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

In questo modo, i tuoi clienti possono scegliere la versione da utilizzare e controllare quando eseguire la migrazione alla nuova versione. L'ESP contrassegna ogni richiesta con il numero di versione prima di indirizzarla al metodo applicabile nel backend. Poiché ogni richiesta è contrassegnata da un numero di versione:

  • I grafici e i log in Endpoints > Servizi mostrano le richieste di ogni versione principale dell'API e il totale aggregato di tutte le versioni. Puoi filtrare la visualizzazione in base a una versione specifica. In questo modo, puoi farti un'idea chiara di quanto traffico riceve ogni versione. I log possono persino indicare quali client utilizzano quale versione.

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

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

Esempio di ciclo di vita dell'API

Questa sezione descrive l'evoluzione tipica di un servizio.

Versione 1

Inizialmente, esegui il deployment della versione 1 del servizio API My Awesome Echo. L'API viene fornita da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Nei grafici e nei log in Endpoints > Servizi, vedi tutto il traffico su 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 a 1.1. Incrementa il numero di versione secondaria perché questa modifica non interrompe il codice client. Esegui il deployment e testa la modifica in un ambiente di gestione temporanea per assicurarti che funzioni.

Successivamente, esegui il deployment della configurazione OpenAPI e del backend API nell'ambiente di produzione. L'API viene ancora servita da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, ma ora i chiamanti possono effettuare richieste al nuovo metodo. Poiché non hai modificato l'interfaccia con i metodi precedenti, i tuoi clienti non devono modificare e ridistribuire i propri client, che possono continuare a inviare richieste al metodo precedente come prima.

In Endpoint > Servizi, il traffico pubblicato è ora alla versione 1.1. Se selezioni un intervallo di tempo precedente da visualizzare, vengono mostrate la versione precedente nei grafici e nei log, che forniscono una cronologia etichettata delle implementazioni.

Versione 2.0

Nel tempo, ti rendi conto che devi apportare una modifica incompatibile con le versioni precedenti a un metodo esistente. Poiché è importante non interrompere il codice client dei tuoi clienti, decidi di mantenere due versioni dell'API. Lasci il vecchio metodo così com'è e implementi la nuova versione. Crea un altro file di configurazione OpenAPI per la versione 2.0 e configura la nuova versione in modo che venga pubblicata da my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Il file di configurazione OpenAPI originale punta ancora alla vecchia versione del metodo, mentre il nuovo file di configurazione OpenAPI punta alla nuova versione del metodo.

Esegui il deployment dei file di configurazione OpenAPI sia della versione 1 sia della versione 2 contemporaneamente e il redeployment del backend, che ora contiene entrambe le versioni del metodo. Per maggiori dettagli, consulta la sezione Controllo delle versioni di un'API.

Dopo il deployment, Endpoints > Servizi mostra che stai pubblicando due versioni della tua API e puoi vedere la quantità di traffico che riceve ciascuna versione. I client v1 possono continuare a chiamare /v1, ma possono anche chiamare /v2 per utilizzare la nuova versione del metodo. Il modo in cui gestisci il controllo delle versioni nel codice di backend dipende dal framework API che utilizzi. Per un esempio che utilizza le servlet, consulta Endpoints e Java con esempio di più versioni.

Disattivazione della versione 1

Con il tempo, man mano che i tuoi clienti eseguono la migrazione e vedi che tutto il traffico verso la v1 si è interrotto, puoi interromperne la pubblicazione. Per rimuovere la versione 1 dell'API, esegui il deployment solo del file di configurazione OpenAPI della versione 2 ed esegui nuovamente il deployment del backend. Ora puoi rimuovere in sicurezza il codice che implementava la versione 1 dal backend. Endpoint > Servizi conserva i dati storici della versione 1.x.

Servizi di allestimento

Come best practice, ti consigliamo di eseguire gli aggiornamenti del servizio Endpoints in modo da poterlo testare prima che raggiunga i tuoi clienti. Ti consigliamo inoltre di creare un progettoGoogle Cloud separato per la gestione temporanea del servizio, in modo che sia isolato dalla produzione. Ad esempio, le quote di Google sono generalmente condivise dalle risorse all'interno di un progetto. Pertanto, se inserisci il servizio di staging nello stesso progetto del servizio di produzione, un ciclo for errato, ad esempio, potrebbe causare un'interruzione del servizio di produzione.

Ti consigliamo di ideare un Google Cloud nome del progetto che indichi chiaramente che è per la 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 aggiungere -prod ai progetti di produzione per indicare chiaramente che il progetto contiene 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 gestire file di configurazione API separati per i progetti di staging e produzione oppure utilizzare un insieme di file di configurazione API e ideare una procedura in cui modifichi il nome del servizio in modo che corrisponda al nome del progetto in cui esegui il deployment.

Passaggi successivi