Questo argomento descrive le strategie di gestione delle versioni utilizzate dalle API Google. Nella in generale, queste strategie si applicano a tutti i servizi gestiti da Google.
A volte è necessario apportare modifiche non compatibili con le versioni precedenti (o "di interruzione") a un'API. Questi tipi di modifiche possono causare problemi o interruzioni del codice delle dipendenze dalla funzionalità originale.
Le API di Google utilizzano uno schema di controllo delle versioni per impedire le modifiche che provocano un errore. Inoltre, Le API di Google rendono alcune funzionalità disponibili solo in determinati livelli di stabilità, come i componenti alfa e beta.
Consulenza
Tutte le interfacce delle API di Google devono fornire un numero di versione principale, ovvero codificata alla fine del pacchetto protobuf e inclusa come prima parte del il percorso URI per le API REST. Se un'API introduce una modifica che comporta una interruzione, ad esempio la rimozione o la ridenominazione di un campo, deve incrementare il numero di versione dell'API per garantire che il codice utente esistente non si interrompa improvvisamente.
La nuova versione principale di un'API non deve dipendere da una versione principale precedente di la stessa API. Un'API può dipendere da altre API, con l'aspettativa che il chiamante comprende il rischio di dipendenza e stabilità associato a queste API. In questo scenario, una versione stabile dell'API deve dipendere solo da versioni stabili di altre API.
Versioni diverse della stessa API devono essere in grado di funzionare contemporaneamente all'interno di una singola applicazione client per un periodo di transizione ragionevole. Questo periodo di tempo consente al cliente di passare senza problemi alla versione più recente. Una versione precedente deve passare attraverso un periodo di ritiro ragionevole e ben comunicato prima di essere chiusa.
Per le release con stabilità alpha o beta, le API devono aggiungere il livello di stabilità dopo il numero di versione principale nel pacchetto protobuf e nel percorso URI utilizzando una di queste strategie:
- Controllo delle versioni basato sul canale (consigliato)
- Controllo delle versioni basato su release
- Controllo delle versioni basato sulla visibilità
Controllo delle versioni basato sul canale
Un canale stabile è una release a lungo termine con un determinato livello di stabilità che riceve aggiornamenti in-place. Non esiste più di un canale per livello di stabilità per una versione principale. Questa strategia prevede fino a tre canali disponibili: alpha, beta e stabile.
Al canale alpha e beta deve essere aggiunto il livello di stabilità alla versione, mentre al canale stabile non deve essere aggiunto il livello di stabilità.
Ad esempio, v1 è una versione accettabile per il canale stabile, ma v1beta o v1alpha non lo sono. Analogamente, v1beta o v1alpha sono versioni accettabili per il rispettivo canale beta e alpha, ma v1 non è accettabile per nessuno dei due. Ciascuno di questi canali riceve nuove funzionalità e aggiornamenti "in-place".
La funzionalità del canale beta deve essere un superset della funzionalità del canale stabile e la funzionalità del canale alpha deve essere un superset della funzionalità del canale beta.
Ritiro della funzionalità dell'API
Gli elementi dell'API (campi, messaggi, RPC) possono essere contrassegnati come obsoleti in qualsiasi canale per indicare che non devono più essere utilizzati:
// Represents a scroll. Books are preferred over scrolls.
message Scroll {
option deprecated = true;
// ...
}
Le funzionalità dell'API deprecate non devono passare dalla versione alpha alla versione beta né alla fase beta stabile. In altre parole, la funzionalità non deve essere "precedentemente ritirata" in nessun canale.
Le funzionalità del canale beta potrebbero essere rimosse dopo il ritiro per un periodo di tempo sufficiente; consigliamo 180 giorni. Per le funzionalità esistenti solo nel canale alpha, il ritiro è facoltativo e la funzionalità potrebbe essere rimossa senza preavviso. Se una funzionalità viene ritirata nel canale alpha di un'API prima della rimozione, l'API deve applicare la stessa annotazione e può utilizzare qualsiasi periodo di tempo desiderato.
Controllo delle versioni basato su release
Una versione individuale è una versione alpha o beta che dovrebbe essere disponibile per un periodo di tempo limitato prima che la sua funzionalità venga incorporata nel canale stabile, dopodiché la release individuale verrà chiusa. Quando utilizzi una strategia di controllo delle versioni basata sulla release, un'API può avere un numero qualsiasi le singole release per ogni livello di stabilità.
Le release alpha e beta devono includere il livello di stabilità aggiunto alla sezione
e un numero di release incrementale. Ad esempio, v1beta1 o
v1alpha5. Le API devono documentare l'ordine cronologico di queste versioni nella loro documentazione (ad esempio nei commenti).
Ogni release alpha o beta può essere aggiornata affinché sia compatibile con le versioni precedenti
modifiche. Per le release beta, gli aggiornamenti non compatibili con le versioni precedenti devono essere apportati incrementando il numero della release e pubblicando una nuova release con la modifica.
Ad esempio, se la versione corrente è v1beta1, la successiva sarà v1beta2.
Le release alpha e beta devono essere chiuse dopo che le relative funzionalità vengono integrate nel canale stabile. Una release alpha può essere interrotta in qualsiasi momento, mentre una release beta dovrebbe consentire agli utenti un periodo di transizione ragionevole; consigliamo 180 giorni.
Controllo delle versioni basato sulla visibilità
Visibilità delle API è una funzionalità avanzata fornita dall'infrastruttura API di Google. Consente ai produttori di API di esporre più visualizzazioni di API esterne da un'unica API interna e ogni visualizzazione è associata a un'etichetta di visibilità dell'API, ad esempio:
import "google/api/visibility.proto";
message Resource {
string name = 1;
// Preview. Do not use this feature for production.
string display_name = 2
[(google.api.field_visibility).restriction = "PREVIEW"];
}
Un'etichetta di visibilità è una stringa sensibile alle maiuscole che può essere utilizzata per taggare qualsiasi API
. Per convenzione, le etichette di visibilità devono sempre usare le maiuscole.
Un'etichetta PUBLIC implicita viene applicata a tutti gli elementi dell'API, a meno che non venga
l'etichetta di visibilità viene applicata come nell'esempio precedente.
Ogni etichetta di visibilità è una lista consentita. I produttori di API devono concedere le etichette di visibilità ai consumatori di API affinché possano utilizzare le funzionalità dell'API associate alle etichette. In altre parole, un'etichetta di visibilità dell'API è come una versione dell'API con ACL.
È possibile applicare più etichette di visibilità a un elemento utilizzando una stringa separata da virgole (ad es. "PREVIEW,TRUSTED_TESTER"). Quando vengono utilizzate più etichette di visibilità, il client ha bisogno di una sola di queste (OR logico).
Una singola richiesta API può utilizzare una sola etichetta di visibilità. Per impostazione predefinita, viene utilizzata l'etichetta di visibilità concessa al consumer dell'API. Un cliente può inviare richieste con un'etichetta di visibilità esplicita come segue:
GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW
I produttori di API possono utilizzare la visibilità dell'API per il controllo delle versioni, ad esempioINTERNAL e PREVIEW. Una nuova funzionalità dell'API inizia con l'etichetta INTERNAL,
poi passa all'etichetta PREVIEW. Quando la funzionalità è stabile e diventa di dominio pubblico, tutte le etichette di visibilità dell'API vengono rimosse dalla definizione dell'API.
In generale, la visibilità dell'API è più facile da implementare rispetto al versionamento dell'API per le modifiche incrementali, ma dipende dal supporto di un'infrastruttura API sofisticata. Le API Google Cloud spesso usano la visibilità delle API per le funzionalità in anteprima.