Questo argomento descrive le strategie di gestione delle versioni utilizzate dalle API Google. Nel in generale, queste strategie si applicano a tutti i servizi gestiti da Google.
A volte è necessario apportare modifiche incompatibili con le versioni precedenti (o "infrangere") a un'API. Questi tipi di modifiche possono causare problemi o guasti al codice che ha 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 provoca un errore, come rimuovendo o rinominando un campo, deve incrementare il numero di versione API del campo 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. Questa volta di passaggio alla versione più recente. Un modello più vecchio versione deve attraversare un periodo di deprecazione ragionevole e ben comunicato prima dell'arresto.
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 percorso dell'URI che utilizza una delle seguenti strategie:
- Controllo delle versioni basato sul canale (consigliato)
- Controllo delle versioni basato su release
- Controllo delle versioni basato sulla visibilità
Controllo versioni basato sul canale
Un canale di stabilità è una release di lunga durata a un determinato livello di stabilità che riceve aggiornamenti sul posto. 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.
I canali alfa e beta devono avere il loro livello di stabilità aggiunto alla sezione
standard, ma il canale stabile non deve includere 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 i rispettivi canali beta e alfa, ma v1 non è accettabile per
. Ciascuno di questi canali riceve nuove funzionalità e aggiornamenti "in-place".
Le funzionalità del canale beta devono essere un soprainsieme delle funzionalità del canale stabile e la funzionalità del canale alfa deve essere un soprainsieme di le funzionalità del canale beta.
Ritiro della funzionalità dell'API
Gli elementi dell'API (campi, messaggi, RPC) possono essere contrassegnati come deprecati in qualsiasi 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 ritirate non devono passare dalla versione alpha alla versione beta né dalla versione beta alla versione stabile. In altre parole, la funzionalità non deve arrivare "pre-deprecata" in qualsiasi canale.
Le funzionalità del canale beta potrebbero essere rimosse dopo il ritiro per un periodo di tempo sufficiente; consigliamo 180 giorni. Per funzionalità esistenti solo nel canale alfa, il ritiro è facoltativo e la funzionalità potrebbe essere rimosso senza preavviso. Se la funzionalità viene deprecata in un'API canale alfa prima della rimozione, l'API deve applicare la stessa annotazione e può utilizzare il 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 relativa documentazione (come i commenti).
Ogni release alpha o beta può essere aggiornata affinché sia compatibile con le versioni precedenti
modifiche. Per le versioni beta, gli aggiornamenti incompatibili con le versioni precedenti devono essere effettuati
incrementare il numero della release e pubblicare una nuova release con la modifica.
Ad esempio, se la versione corrente è v1beta1, la successiva sarà v1beta2.
Le release alpha e beta devono essere disattivate al termine della loro funzionalità raggiunge il canale stabile. Una release alpha può essere disattivata in qualsiasi momento, mentre una versione beta dovrebbe concedere agli utenti un periodo di transizione ragionevole; noi consiglia 180 giorni.
Controllo delle versioni basato sulla visibilità
La visibilità dell'API è una funzionalità avanzata fornita dall'infrastruttura delle API di Google. Consente ai produttori di API di esporre più viste API esterne da un server Superficie API e ogni vista è associata a un'etichetta di visibilità dell'API, ad esempio come:
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 elemento dell'API. Per convenzione, le etichette di visibilità devono sempre usare le maiuscole.
A tutti gli elementi dell'API viene applicata un'etichetta PUBLIC implicita, a meno che non venga applicata un'etichetta di visibilità esplicita come nell'esempio precedente.
Ogni etichetta di visibilità è una lista consentita. I produttori di API devono concedere la visibilità le etichette ai consumer delle API affinché possano utilizzare le funzionalità API associate alle etichette. In altre parole, un'etichetta di visibilità API è come una versione API inserita in ACL.
È possibile applicare più etichette di visibilità a un elemento utilizzando un
stringa separata da virgole (ad es. "PREVIEW,TRUSTED_TESTER"). Quando più
vengono utilizzate le etichette di visibilità, il cliente ha bisogno solo di una
(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 client 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à delle API per il controllo delle versioni delle API, ad esempio:
INTERNAL e PREVIEW. Una nuova funzionalità dell'API inizia con l'etichetta INTERNAL,
quindi 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 dell'infrastruttura API sofisticata. Le API Google Cloud spesso usano la visibilità delle API per le funzionalità in anteprima.