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 der folgenden Ansätze hinzugefügt werden:
- Versionsverwaltung auf Kanalebene (empfohlen)
- Versionsverwaltung auf Release-Ebene
Versionsverwaltung 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 Alpha- und Beta-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:
// A representation of a scroll.
// Books are now 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.