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 Versionen mit Alpha- oder Beta-Stabilität muss für APIs die Stabilitätsstufe nach der Hauptversionsnummer im Protobuf-Paket und im URI-Pfad nach einem dieser Ansätze hinzugefügt werden:
- Versionsverwaltung auf Kanalebene (empfohlen)
- Versionsverwaltung 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. Ebenso sind v1beta oder v1alpha akzeptable Versionen für den jeweiligen Beta- und Alpha-Kanal. v1 ist aber für beide Kanäle nicht akzeptabel. 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 Releaseebene
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
API-Sichtbarkeit ist ein erweitertes Feature, das von der Google API-Infrastruktur bereitgestellt wird. API-Ersteller können mehrere externe API-Ansichten einer internen API-Oberfläche bereitstellen. Jede Ansicht ist mit einem API-Sichtbarkeitslabel verknüpft, zum 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"];
}
Bei einem Sichtbarkeitslabel handelt es sich um einen String, bei dem die Groß- und Kleinschreibung berücksichtigt wird. Er kann zum Taggen eines API-Elements verwendet werden. Konventionsgemäß sollten Sichtbarkeitslabels immer in GROSSBUCHSTABEN verwenden.
Ein implizites PUBLIC-Label wird auf alle API-Elemente angewendet, es sei denn, wie im obigen Beispiel wird ein explizites Sichtbarkeitslabel angewendet.
Jedes Sichtbarkeitslabel ist eine Zulassungsliste. API-Ersteller müssen API-Nutzern Sichtbarkeitslabels zuweisen, damit sie API-Features verwenden können, die mit den Labels verknüpft sind. Mit anderen Worten: Ein API-Sichtbarkeitslabel ist wie eine ACL-API-Version.
Mithilfe eines durch Kommas getrennten Strings (z. B. "PREVIEW,TRUSTED_TESTER") können mehrere Sichtbarkeitslabels auf ein Element angewendet werden. Wenn mehrere Sichtbarkeitslabels verwendet werden, benötigt der Client nur eines der Sichtbarkeitslabels (logisches OR).
Eine einzelne API-Anfrage kann nur ein Sichtbarkeitslabel verwenden. Standardmäßig wird das dem API-Nutzer zugewiesene 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 die API-Sichtbarkeit für API-Versionen wie INTERNAL und PREVIEW verwenden. Ein neues API-Feature beginnt mit dem Label INTERNAL und geht dann zum Label PREVIEW über. Wenn das Feature stabil ist und allgemein verfügbar ist, werden alle API-Sichtbarkeitslabels aus der API-Definition entfernt.
Im Allgemeinen ist die Implementierung der API-Sichtbarkeit für inkrementelle Änderungen einfacher zu implementieren als die API-Versionsverwaltung. Dies hängt jedoch von komplexen API-Infrastrukturunterstützung ab. Google Cloud APIs verwenden häufig die API-Sichtbarkeit für Vorschaufeatures.