Controllo delle versioni

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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 "interruzione" di un'API). Questi tipi di modifiche possono causare problemi o interruzioni del codice che dipende dalle funzionalità originali.

Le API di Google utilizzano uno schema di controllo delle versioni per evitare modifiche che provocano errori. Inoltre, le API di Google rendono disponibili alcune funzionalità solo al di fuori di determinati livelli di stabilità, come i componenti alpha e beta.

Consulenza

Tutte le interfacce delle API di Google devono fornire un numero di versione principale, che è codificato alla fine del pacchetto protobuf e incluso nella prima parte del percorso dell'URI delle API REST. Se un'API introduce una modifica che provoca un errore, come la rimozione o la ridenominazione di un campo, deve aumentare il numero di versione dell'API per assicurare che il codice utente esistente non subisca interruzioni.

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, con la speranza che il chiamante comprenda il rischio di dipendenza e stabilità associato a tali API. In questo scenario, una versione API stabile 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 precedente deve deve superare un periodo di ritiro ragionevole e ben comunicato prima di essere arrestato.

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 di stabilità è una release di lunga durata a un determinato livello di stabilità che riceve aggiornamenti in sede. Non c'è più di un canale per livello di stabilità per una versione principale. In base a questa strategia, sono disponibili fino a tre canali: alfa, beta e stabile.

I canali Alpha e Beta devono avere il proprio livello di stabilità aggiunto alla versione, ma il canale stabile non deve avere il livello di stabilità aggiunto. Ad esempio, v1 è una versione accettabile per il canale stabile, mentre v1beta o v1alpha non lo sono. Analogamente, v1beta o v1alpha sono versioni accettabili per i rispettivi canali beta e alpha, ma v1 non è accettabile per nessuno dei due. Ciascuno di questi canali riceve nuove funzionalità e aggiornamenti "in loco".

La funzionalità del canale beta deve essere un soprainsieme della funzionalità stabile del canale e la funzionalità del canale alpha deve essere un soprainsieme della 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;

  // ...
}

La funzionalità delle API deprecate non deve passare da alpha a beta o da beta a stabile. In altre parole, la funzionalità non deve arrivare "in precedenza" in qualsiasi canale.

La funzionalità del canale beta potrebbe essere rimossa dopo che questa verrà ritirata per un periodo sufficiente; consigliamo di non farlo per 180 giorni. Per le funzionalità che esistono solo nel canale alfa, il ritiro è facoltativo e la funzionalità può essere rimossa senza preavviso. Se la funzionalità viene ritirata in un canale alpha di un'API prima della rimozione, l'API dovrebbe applicare la stessa annotazione e utilizzare il periodo di tempo che preferisce.

Controllo delle versioni basato su release

Una singola release è una release 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à disattivata. Quando utilizzi una strategia di controllo delle versioni basata sulle release, un'API può avere un numero qualsiasi di singole release ad ogni livello di stabilità.

Le release alpha e beta devono avere il livello di stabilità aggiunto 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 documentazione (ad esempio i commenti).

Ogni release alpha o beta può essere aggiornata per essere applicata con modifiche compatibili con le versioni precedenti. Per le release beta, gli aggiornamenti incompatibili con le versioni precedenti devono essere apportati incrementando il numero di release e pubblicando una nuova release con la modifica. Ad esempio, se la versione corrente è v1beta1, v1beta2 verrà rilasciata in seguito.

Le release alpha e beta devono essere chiuse dopo che la loro funzionalità raggiunge il canale stabile. Una release alpha potrebbe essere disattivata in qualsiasi momento, mentre una release beta dovrebbe consentire agli utenti un periodo di transizione ragionevole; consigliamo pertanto 180 giorni.

Controllo delle versioni basato sulla visibilità

Visibilità API è una funzionalità avanzata fornita dall'infrastruttura API di Google. Consente ai produttori di API di esporre più viste API esterne da una piattaforma API interna e ogni vista è associata a un'etichetta di visibilità API, 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 API. Per convenzione, le etichette di visibilità devono utilizzare sempre le maiuscole. A tutti gli elementi 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 etichette di visibilità ai consumatori API affinché possano utilizzare le funzionalità API associate alle etichette. In altre parole, un'etichetta di visibilità API è simile a una versione API ACL'ed.

È possibile applicare più etichette di visibilità a un elemento utilizzando una stringa separata da virgole (ad esempio "PREVIEW,TRUSTED_TESTER"). Quando vengono utilizzate più etichette di visibilità, il client ha bisogno di solo una delle etichette di visibilità (logica OR).

Una singola richiesta API può utilizzare una sola etichetta di visibilità. Per impostazione predefinita, viene utilizzata l'etichetta di visibilità concessa al consumer 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, come INTERNAL e PREVIEW. Una nuova funzionalità dell'API inizia con l'etichetta INTERNAL, poi passa all'etichetta PREVIEW. Quando la funzionalità sarà stabile e diventerà disponibile a livello generale, tutte le etichette di visibilità API vengono rimosse dalla definizione dell'API.

In generale, la visibilità API è più facile da implementare rispetto al controllo delle versioni dell'API per le modifiche incrementali, ma dipende dal supporto dell'infrastruttura API. Le API Google Cloud spesso usano la visibilità API per le funzionalità di anteprima.