Questo argomento descrive le strategie di controllo delle versioni utilizzate dalle API di Google. In generale, queste strategie si applicano a tutti i servizi gestiti da Google.
A volte è necessario apportare modifiche incompatibili con le versioni precedenti (o "interrompenti") a un'API. Questo tipo di modifiche può causare problemi o interruzioni del codice che ha dipendenze dalla funzionalità originale.
Le API di Google utilizzano uno schema di controllo delle versioni per impedire modifiche che provocano un errore. Inoltre, le API di Google rendono disponibili alcune funzionalità solo per determinati livelli di stabilità, ad esempio i componenti alpha e beta.
Consulenza
Tutte le interfacce delle API di Google devono fornire un numero di versione principale, che viene codificato alla fine del pacchetto protobuf e incluso come prima parte del percorso URI per le API REST. Se un'API introduce una modifica che provoca un errore, come 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.
Una nuova versione principale di un'API non deve dipendere da una versione principale precedente della stessa API. Un'API potrebbe dipendere da altre API, nell'aspettativa che il chiamante comprenda 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 client di passare senza problemi alla versione più recente. Una versione meno recente deve essere sottoposta a un periodo di deprecazione ragionevole e ben comunicato prima di essere disattivata.
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 il percorso URI utilizzando una delle seguenti strategie:
- Controllo delle versioni basato sul canale (consigliato)
- Controllo delle versioni basato sulla release
- Controllo delle versioni basato sulla visibilità
Controllo delle versioni basato sul canale
Un canale di stabilità è una release di lunga durata con un determinato livello di stabilità che riceve aggiornamenti in loco. Non c'è più di un canale per livello di stabilità per una versione principale. Questa strategia prevede fino a tre canali disponibili: alpha, beta e stabile.
Ai canali alfa e beta deve essere aggiunto il livello di stabilità alla versione, ma al canale stabile non deve essere aggiunto il livello di stabilità.
Ad esempio, v1 è una versione accettabile per il canale stabile, al contrario di v1beta o v1alpha. Analogamente, v1beta o v1alpha sono versioni accettabili
per i rispettivi canali beta e alfa, ma v1 non è accettabile
per entrambe le versioni. Ciascuno di questi canali riceve nuove funzioni e aggiornamenti "in loco".
Le funzionalità del canale beta devono essere un soprainsieme delle funzionalità del canale stabile, mentre il canale alfa deve essere un soprainsieme di funzionalità del canale beta.
Ritiro della funzionalità API
Gli elementi API (campi, messaggi, RPC) possono essere contrassegnati come deprecati 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à delle API deprecate non devono passare da alpha a beta né passare dalla versione beta a stabile. In altre parole, la funzionalità non deve pervenire "pre-deprecata" in nessun canale.
La funzionalità del canale beta potrebbe essere rimossa dopo essere stato ritirato per un periodo sufficiente (consigliamo 180 giorni). Il ritiro delle funzionalità presenti solo nel canale alfa è facoltativo e la funzionalità potrebbe essere rimossa senza preavviso. Se la funzionalità viene ritirata nel canale alfa di un'API prima della rimozione, l'API deve applicare la stessa annotazione e può utilizzare il periodo di tempo desiderato.
Controllo delle versioni basato sulla release
Una singola release è 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 singola release verrà arrestata. Quando utilizzi una strategia di controllo delle versioni basata sulla release, un'API può avere un numero illimitato di singole release per ogni livello di stabilità.
Le versioni alpha e beta devono avere aggiunto il livello di stabilità alla versione, seguito da un numero di release incrementale. Ad esempio, v1beta1 o
v1alpha5. Le API devono documentare l'ordine cronologico di queste versioni nella propria documentazione (ad esempio, i commenti).
Ogni release alpha o beta può essere aggiornata con modifiche compatibili con le versioni precedenti. Per le release beta, gli aggiornamenti non compatibili con le versioni precedenti dovrebbero essere apportati incrementando il numero di release e pubblicando una nuova release con la modifica.
Ad esempio, se la versione corrente è v1beta1, verrà rilasciata v1beta2.
Le release alpha e beta devono essere arrestate dopo che la loro funzionalità raggiunge il canale stabile. Una release alpha può essere disattivata in qualsiasi momento, mentre una versione beta deve concedere agli utenti un periodo di transizione ragionevole (consigliamo 180 giorni).
Controllo delle versioni basato sulla visibilità
Visibilità API è una funzionalità avanzata fornita dall'infrastruttura delle API di Google. Consente ai producer di API di esporre più viste API esterne da una singola piattaforma API interna e ogni vista è 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 elemento API. Per convenzione, le etichette di visibilità devono sempre utilizzare il maiuscolo.
Un'etichetta PUBLIC implicita viene applicata a tutti gli elementi dell'API, a meno che non venga applicata un'etichetta di visibilità esplicita, come nell'esempio precedente.
Ogni etichetta di visibilità è una lista consentita. I producer di API devono concedere etichette di visibilità ai consumer delle API affinché possano utilizzare le funzionalità API associate alle etichette. In altre parole, un'etichetta di visibilità API è simile a una versione dell'API ACL.
È possibile applicare a un elemento più etichette di visibilità utilizzando una stringa separata da virgole (ad es. "PREVIEW,TRUSTED_TESTER"). Se vengono utilizzate più etichette di visibilità, il client ha bisogno solo di una delle etichette di visibilità (OR logiche).
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à API inizia con l'etichetta INTERNAL,
poi passa all'etichetta PREVIEW. Quando la funzionalità è stabile e diventa disponibile pubblicamente, tutte le etichette di visibilità API vengono rimosse dalla definizione dell'API.
In generale, la visibilità delle API è più facile da implementare rispetto al controllo delle versioni per le modifiche incrementali, ma dipende dal supporto di un'infrastruttura API sofisticata. Le API Google Cloud spesso utilizzano la visibilità API per le funzionalità in anteprima.