API versionieren

Diese Seite enthält ausführliche Konfigurations- und Bereitstellungsanleitungen zum Ändern der Versionsnummer einer API. Welche Anleitung Sie verwenden, hängt davon ab, ob die Änderungen an der API abwärtskompatibel sind.

  • Wenn die neue API-Version abwärtskompatible Änderungen enthält, beispielsweise neue Felder oder Methoden, lesen Sie die Informationen unter Abwärtskompatible Änderungen.
  • Wenn Änderungen an einer vorhandenen Methode in der neuen API dazu führen, dass der Clientcode Ihrer Kunden nicht mehr funktioniert, lesen Sie die Informationen unter Abwärtsinkompatible Änderungen.

Weitere Informationen und Best Practices finden Sie unter API-Lebenszyklus verwalten.

Abwärtskompatible Änderungen

Wenn die Änderungen an der API mit dem vorhandenen Clientcode abwärtskompatibel sind, erhöhen Sie am besten die Nebenversionsnummer der API, bevor Sie die neue Version bereitstellen. Obwohl Cloud Endpoints nur jeweils eine Nebenversion einer API ausführt, wird die Versionsnummer dennoch in den Grafiken und Logs unter Endpoints > Dienste angezeigt. Durch Erhöhung der Nebenversionsnummer vor der Bereitstellung können Sie an den Grafiken und Logs den Verlauf Ihrer Bereitstellungen ablesen.

So erhöhen Sie die Nebenversionsnummer:

  1. Erhöhen Sie in openapi.yaml die Nebenversionsnummer des Feldes info.version. Beispiel: Wenn die aktuelle Version 1.1 lautet, legen Sie info.version auf 1.2 fest:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. Stellen Sie die API-Konfiguration mit der Google Cloud CLI bereit:

    gcloud endpoints services deploy openapi.yaml

  3. Stellen Sie das API-Backend mithilfe der Konfigurations-ID bereit, die im vorherigen Schritt zurückgegeben wurde. Weitere Informationen finden Sie unter API-Backend bereitstellen.

Abwärtsinkompatible Änderungen

Wenn die Änderungen an der API nicht mit dem Clientcode des Kunden kompatibel sind, erhöhen Sie am besten die Hauptversionsnummer der API. In Endpoints können mehrere Hauptversionen einer API gleichzeitig ausgeführt werden. Wenn Sie beide Versionen der API anbieten, können Kunden die gewünschte Version auswählen und selbst entscheiden, wann sie zur neuen Version migrieren.

So führen Sie die vorhandene Version und neue Versionen einer API gleichzeitig aus:

  1. Erstellen Sie separate OpenAPI-Konfigurationsdateien für jede Version, die Sie bereitstellen müssen. Bei diesem Vorgang werden die Dateinamen openapi-v1.yaml und openapi-v2.yaml zu Beispielzwecken verwendet.

  2. Kopieren Sie den Inhalt von openapi-v1.yaml in openapi-v2.yaml.

  3. Konfigurieren Sie in openapi-v1.yaml Folgendes:

    • Legen Sie das Feld info.version auf die vorhandene Versionsnummer fest.
    • Ändern Sie das Feld basePath nicht.

    Beispiel:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. Konfigurieren Sie in openapi-v2.yaml Folgendes:

    • Nicht abwärtskompatible Änderungen vornehmen
    • Legen Sie das Feld info.version auf die neue Versionsnummer fest.
    • Geben Sie im Feld basePath zusätzlich die neue Hauptversionsnummer an.
    • Entfernen Sie den Abschnitt x-google-endpoints. Dieser Abschnitt ist erforderlich, wenn Sie die DNS-IP-Adresse oder das Flag allowCors angeben möchten. Wenn Sie zwei Versionen der API mit zwei yaml-Konfigurationsdateien bereitstellen, kann nur eine davon x-google-endpoints haben. Die Konfiguration gilt jedoch für beide Versionen.

    Beispiel:

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. Stellen Sie beide API-Konfigurationsdateien mit der Google Cloud CLI bereit:

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. Stellen Sie nur ein Backend bereit, das beide Versionen der API bedient. Verwenden Sie dazu die Konfigurations-ID, die im vorherigen Schritt zurückgegeben wurde. Weitere Informationen finden Sie unter API-Backend bereitstellen.

Weitere Informationen