Manchmal ist es notwendig, nicht abwärtskompatible (oder sogar funktionsgefährdende) Änderungen an einer API vorzunehmen. Diese Art von Änderungen kann zu Problemen oder Fehlern bei Code führen, der von der ursprünglichen Funktionalität abhängig ist.
Google APIs nutzen ein Versionsverwaltungsschema, um funktionsgefährdende Änderungen zu verhindern. Darüber hinaus stellen Google APIs einige Funktionen nur unter bestimmten Stabilitätsstufen bereit, z. B. als Alpha- und Beta-Komponenten.
Hinweise
Alle Google API-Schnittstellen müssen eine Hauptversionsnummer haben, die am Ende des Protobuf-Pakets codiert und als erster Teil im URI-Pfad für REST APIs enthalten ist. Wenn für eine API eine funktionsgefährdende Änderung ausgeführt wurde, z. B. das Entfernen oder Umbenennen eines Felds, muss die API-Versionsnummer erhöht werden, um zu gewährleisten, dass der vorhandene Nutzercode nicht plötzlich funktionsunfähig wird.
Eine neue Hauptversion einer API darf nicht von einer früheren Hauptversion der gleichen API abhängig sein. Eine API kann von anderen APIs abhängig sein, wenn der Aufrufer das mit diesen APIs verbundene Abhängigkeits- und Stabilitätsrisiko kennt. In diesem Szenario darf eine stabile API-Version immer nur von stabilen Versionen anderer APIs abhängen.
Verschiedene Versionen der gleichen API müssen in einer einzelnen Clientanwendung für einen angemessenen Übergangszeitraum gleichzeitig funktionsfähig sein. In diesem Zeitraum kann der Client problemlos auf die neuere Version umsteigen. Für eine ältere Version muss eine angemessene, gut kommunizierte Verfallsfrist gelten, bevor sie eingestellt wird.
Bei Releases mit Alpha- oder Betastabilität müssen die APIs nach der Hauptversionsnummer im protobuf-Paket und im URI-Pfad mit einem der folgenden Werte angehängt werden: folgende Strategien:
- Versionsverwaltung auf Kanalebene (empfohlen)
- Versionierung auf Releaseebene
- Sichtbarkeitsbasierte Versionsverwaltung
Versionierung auf Kanalebene
Ein Stabilitätskanal ist eine langlebige Version mit einer bestimmten Stabilitätsstufe, die direkte Aktualisierungen übernimmt. Für eine Hauptversion gibt es immer nur einen Kanal pro Stabilitätsstufe. Im Rahmen dieses Ansatzes stehen bis zu drei Kanäle zur Verfügung: Alpha, Beta und Stabil.
Für den Alpha- und Beta-Kanal muss die Stabilitätsstufe an die Versionsnummer angehängt werden. Für den stabilen Kanal darf die Stabilitätsstufe jedoch nicht angehängt werden.
Beispielsweise ist v1 eine akzeptable Version für den stabilen Kanal, v1beta oder v1alpha jedoch nicht. Entsprechend sind v1beta oder v1alpha zulässige Versionen für die jeweilige Betaversion und den Alphakanal. v1 ist jedoch nicht zulässig. Jeder dieser Kanäle erhält neue Features sowie direkte Aktualisierungen.
Die Funktionalität des Beta-Kanals muss eine Obermenge der Funktionalität des stabilen Kanals und die Funktionalität des Alpha-Kanals muss eine Obermenge der Funktionalität des Beta-Kanals sein.
Verworfene API-Funktionalität
API-Elemente (Felder, Nachrichten, RPCs) können in einem Kanal als verworfen markiert werden, um anzugeben, dass sie nicht mehr verwendet werden sollen:
// Represents a scroll. Books are preferred over scrolls.
message Scroll {
option deprecated = true;
// ...
}
Eine verworfene API-Funktionalität darf nicht von Alpha zu Beta und nicht von Beta zu Stabil weitergegeben werden. Mit anderen Worten: Eine Funktion darf nicht in einem Kanal als bereits verworfen ankommen.
Die Funktionalität des Beta-Kanals kann entfernt werden, wenn sie bereits in einem ausreichenden Zeitraum verworfen ist. Wir empfehlen dafür 180 Tage. Für Funktionen, die nur im Alpha-Kanal vorhanden sind, ist das Verwerfen optional und die Funktionalität kann ohne vorherige Bekanntgabe entfernt werden. Wenn die Funktionalität im Alpha-Kanal einer API vor dem Entfernen verworfen wurde, sollte die API die gleiche Annotation anwenden und sie kann dafür einen beliebigen Zeitrahmen nutzen.
Versionsverwaltung auf Release-Ebene
Ein Einzel-Release ist eine Alpha- oder Beta-Version, die voraussichtlich für einen begrenzten Zeitraum verfügbar sein wird, bevor ihre Funktionalität in den stabilen Kanal übernommen wird. Danach wird die Einzelversion eingestellt. Bei Anwendung der Release-basierten Versionsverwaltungsstrategie kann eine API auf jeder Stabilitätsstufe eine beliebige Anzahl einzelner Releases enthalten.
Bei Alpha- und Beta-Versionen muss die Stabilitätsstufe an die Version angehängt werden, gefolgt von einer inkrementellen Versionsnummer. Beispiel: v1beta1oder v1alpha5. APIs sollten die chronologische Reihenfolge dieser Versionen dokumentieren (z. B. durch Kommentare).
Jede Alpha- oder Beta-Version kann mit abwärtskompatiblen Änderungen direkt aktualisiert werden. Bei Beta-Versionen sollten abwärtsinkompatible Aktualisierungen durch Erhöhen der Versionsnummer und durch Veröffentlichen einer neuen Version mit der Änderung vorgenommen werden.
Wenn die aktuelle Version beispielsweise v1beta1 ist, wird als Nächstes v1beta2 freigegeben.
Alpha- und Beta-Versionen sollten eingestellt werden, wenn ihre Funktionalität den stabilen Kanal erreicht hat. Eine Alpha-Version kann jederzeit eingestellt werden, während für eine Beta-Version Nutzern eine angemessene Übergangszeit gewähren werden sollte. Wir empfehlen dafür 180 Tage.
Sichtbarkeitsbasierte Versionsverwaltung
Die API-Sichtbarkeit ist eine erweiterte Funktion der Google API-Infrastruktur. API-Produzenten können dadurch mehrere externe API-Ansichten über eine interne API-Oberfläche bereitstellen. Jede Ansicht ist einem API-Sichtbarkeitslabel zugeordnet. Beispiel:
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"];
}
Ein Sichtbarkeitslabel ist ein String, bei dem die Groß- und Kleinschreibung berücksichtigt wird. Sie können damit alle API-Elemente taggen. In der Regel sollten Sichtbarkeitslabels immer UPPER verwenden.
Ein implizites PUBLIC-Label wird auf alle API-Elemente angewendet, sofern kein explizites Sichtbarkeitslabel wie im obigen Beispiel angewendet wird.
Jedes Sichtbarkeitslabel ist eine weiße Liste. API-Produzenten müssen API-Nutzern Sichtbarkeitslabels zur Verfügung stellen, damit sie API-Funktionen verwenden können, die mit den Labels verknüpft sind. Ein API-Sichtbarkeitslabel ist also wie eine API-Version mit ACL.
Mit einem kommagetrennten String (z.B. "PREVIEW,TRUSTED_TESTER") können mehrere Sichtbarkeitslabels auf ein Element angewendet werden. Wenn mehrere Sichtbarkeitslabels verwendet werden, benötigt der Client nur ein der Sichtbarkeitslabels (logisches OR).
Eine einzelne API-Anfrage kann nur ein Sichtbarkeitslabel verwenden. Standardmäßig wird das dem API-Nutzer verwendete Sichtbarkeitslabel verwendet. Ein Client kann Anfragen mit einem expliziten Sichtbarkeitslabel so senden:
GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW
API-Ersteller können API-Sichtbarkeit für die API-Versionsverwaltung wie z. B. INTERNAL und PREVIEW verwenden. Eine neue API-Funktion beginnt mit dem Label INTERNAL und wechselt dann zum Label PREVIEW. Wenn die Funktion stabil ist und allgemein verfügbar ist, werden alle API-Sichtbarkeitslabels aus der API-Definition entfernt.
Im Allgemeinen ist die API-Sichtbarkeit einfacher als die API-Versionsverwaltung für inkrementelle Änderungen möglich, hängt jedoch von der komplexen Unterstützung der API-Infrastruktur ab. Die Google Cloud APIs verwenden oft für die Vorschaufunktionen die API-Sichtbarkeit.