Gestione del ciclo di vita delle API

Questa pagina descrive le funzionalità di gestione delle versioni dell'API Cloud Endpoints e fornisce le best practice per la gestione delle versioni e l'implementazione dell'API Endpoints. Le informazioni riportate in questa pagina sono applicabili alle API che utilizzano la specifica OpenAPI. Per le API che utilizzano i framework Cloud Endpoints per l'ambiente standard App Engine, consulta Gestire il versionamento delle API: Java o Gestire il versionamento delle API: Python.

Ti consigliamo di seguire gli stessi principi di base utilizzati da Google per il versionamento delle API e lo staging 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 che includa il numero della versione principale. Ti consigliamo di utilizzare un percorso di base formattato come la lettera v followed by major version number, ad esempio /v1.

  • Quando devi apportare una modifica compatibile con le versioni precedenti, ad esempio l'aggiunta di un nuovo metodo, incrementa il numero della versione secondaria (1.2, 1.3 e così via) nel campo info.version e esegui nuovamente il deployment. Per informazioni dettagliate, consulta Eseguire il versionamento di un'API.

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

    • Incrementa il numero della 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 del backend, che ora contiene entrambe le versioni del metodo. Per informazioni dettagliate, consulta Eseguire il versionamento di un'API.

  • Implementa tutte le principali versioni 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 progetto e lo stesso backend Google Cloud per tutte le versioni principali dell'API e esegui il deployment di tutte le versioni contemporaneamente.
    • Mantiene bassi i costi evitando di eseguire backend superflui.

  • Esegui lo staging dell'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 nel 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 di backend, puoi scegliere di farlo se vuoi.

Funzionalità di gestione delle versioni dell'API Cloud Endpoints

Extensible Service Proxy (ESP) consente di gestire contemporaneamente più versioni principali dell'API 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

In questo modo, i clienti possono scegliere la versione che vogliono utilizzare e controllare quando eseguire la migrazione alla nuova versione. L'ESP contrassegna ogni richiesta con il numero di versione prima di inoltrarla al metodo applicabile nel backend. Poiché ogni richiesta è associata a 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 avrai un'idea chiara di quanto traffico riceve ogni versione. I log possono anche indicare quali client utilizzano quale versione.

  • Quando esegui il nuovo deployment dell'API con un aggiornamento minore del numero di versione, 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 implementazioni.

  • 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

Esegui inizialmente il deployment della versione 1 del servizio API My Awesome Echo. L'API viene pubblicata da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Nei grafici e nei log in Endpoints > Servizi, viene visualizzato 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 a 1.1. Aumenti il numero della versione minore perché questa modifica non interrompe il codice client. Esegui il deployment e testa la modifica in un ambiente di staging per verificare che funzioni.

Successivamente, esegui il deployment della configurazione OpenAPI e del backend dell'API nell'ambiente di produzione. L'API viene ancora pubblicata 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 dei vecchi metodi, i tuoi clienti non devono modificare e eseguire nuovamente il deployment dei propri client. I client possono continuare a inviare richieste al vecchio metodo come prima.

In Endpoint > Servizi, il traffico pubblicato è ora alla versione 1.1. Se selezioni un intervallo di tempo precedente da visualizzare, viene visualizzata la versione precedente nei grafici e nei log, che fornisce una cronologia etichettata dei tuoi implementazioni.

Versione 2.0

Nel tempo, ti rendi conto che devi apportare una modifica non compatibile con le versioni precedenti a un metodo esistente. Poiché è importante non interrompere il codice client dei clienti, decidi di mantenere due versioni dell'API. Lascia il vecchio metodo invariato e implementa 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 fa ancora riferimento alla vecchia versione del metodo, mentre il nuovo file di configurazione OpenAPI fa riferimento alla nuova versione del metodo.

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

Dopo il deployment, Endpoints > Services (Endpoint > Servizi) mostra che stai pubblicando due versioni della tua API e puoi vedere quanto traffico riceve ciascuna versione. I client della versione 1 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 di utilizzo di servlet, consulta Esempio di endpoint e Java con più versioni.

Disattivazione della versione 1

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

Servizi di staging

Come best practice, ti consigliamo di eseguire l'implementazione graduale degli aggiornamenti del servizio Endpoints in modo da poterlo testare prima che raggiunga i clienti. Ti consigliamo inoltre di creare un progetto Google Cloud distinto per l'implementazione 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 creare un nome per il progetto Google Cloud che indichi chiaramente che si tratta di un progetto di staging. Una strategia di denominazione comune è utilizzare lo stesso nome del progetto Google Cloud di produzione, ma con -staging alla fine. Ti consigliamo inoltre di inserire -prod nei progetti di produzione per chiarire 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 di produzione oppure utilizzare un insieme di file di configurazione API e ideare un processo in cui modifichi il nome del servizio in modo che corrisponda al nome del progetto in cui esegui il deployment.

Passaggi successivi