API-Änderungen brauchen separate Versionen? Eine API-Version erstellen und testen

Mit API-Versionen können Clients auf eine geänderte API wechseln, sobald sie bereit sind. Angenommen, eine Bestell-API ändert total von einer Zahl in ein Objekt mit Betrag und Währung. Bestehende Clients könnten fehlschlagen, wenn diese Änderung plötzlich an ihrem bisherigen Endpunkt erscheint. Wenn v1 neben der neuen v2 verfügbar bleibt, haben Clients Zeit für die Umstellung.

Verwende apim-ctgateway-weu im Consumption-Tarif und CloudTrips Petstore weiter. Wir erstellen v1 und v2, kennzeichnen beide mit einem Antwortheader und erhalten die ursprüngliche URL. Beide Versionen verwenden dasselbe Petstore-Backend. Wir stellen in diesem Lab keine neue Anwendung bereit und ändern den JSON-Antwortinhalt nicht.

Funktion	Typischer Einsatz
Version	Einen separat wählbaren API-Vertrag anbieten, häufig für inkompatible Änderungen
Revision	Änderungen innerhalb einer Version vorbereiten und testen, häufig für kompatible Anpassungen

Versionierung macht eine inkompatible Änderung nicht automatisch sicher. Clients müssen die neue Version weiterhin gezielt auswählen und sich an ihren Vertrag anpassen.

Bestehende API vorbereiten

Öffne API Management → apim-ctgateway-weu → APIs → APIs → CloudTrips Petstore.

Wenn du den Policy-Trip durchgeführt hast, erledige zuerst dessen Aufräumschritt. Unter Design → GET /pet/findByStatus → Policy-Codeeditor sollte die Policy der Operation so aussehen:

<policies>
  <inbound><base /></inbound>
  <backend><base /></backend>
  <outbound><base /></outbound>
  <on-error><base /></on-error>
</policies>

Speichere Änderungen. Behalte unter All operations die Policy zum Entfernen der Subscription-Schlüssel vor der Weiterleitung bei und lasse Subscription required aktiviert. So werden die Headerpflicht, das Überschreiben des Abfrageparameters und das Limit von drei Aufrufen aus dem vorherigen Lab nicht in die neuen Versionen kopiert.

v1 erstellen

Öffne in der API-Liste … neben CloudTrips Petstore → Add version:

Version identifier: v1
Versioning scheme: Path
Full API version name: ct-petstore-v1
Products: leer lassen

Wähle Create. Das Portal gruppiert die API in einem Version Set. Klappe die Gruppe auf, um Original und v1 zu sehen.

Original erhält den bisherigen Endpunkt ohne Versionssegment. Diese API wird nicht automatisch in v1 umbenannt. Die neue v1 ist eine separate API-Ressource, die aus der Quell-API erstellt wird.

Wir verwenden Path, damit die gewählte Version in der URL sichtbar ist. APIM unterstützt auch die Versionsauswahl über einen Header oder Abfrageparameter. Alle Versionen eines Version Sets verwenden jedoch das gemeinsam gewählte Verfahren.

Wähle v1 → Settings und prüfe:

Web service URL: https://petstore3.swagger.io/api/v3
API URL suffix: petstore
Subscription required: On

APIM ergänzt das Versionssegment selbst. Ändere das Suffix nicht manuell in petstore/v1 und die Backend-URL nicht in /v1. Petstores eigene Adresse /api/v3 und die Versionskennungen deines Gateways sind unabhängig voneinander.

Antwort von v1 kennzeichnen

Öffne innerhalb von v1 den Bereich Design → All operations → Policy-Codeeditor. Ersetze die Policy dieser Lab-API durch:

<policies>
  <inbound>
    <base />
    <set-header name="Ocp-Apim-Subscription-Key" exists-action="delete" />
    <set-query-parameter name="subscription-key" exists-action="delete" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-header name="X-CloudTrips-API-Version" exists-action="override">
      <value>v1</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Speichere. Die Regeln zum Entfernen des Schlüssels bleiben enthalten; zusätzlich erhalten Backendantworten den Header X-CloudTrips-API-Version: v1. Damit können wir sichtbar prüfen, welche Version die Anfrage verarbeitet hat.

v2 aus v1 erstellen

Öffne … neben dem API-Eintrag v1 → Add version:

Version identifier: v2
Versioning scheme: Path (vom Version Set übernommen)
Full API version name: ct-petstore-v2
Products: leer lassen

Wähle Create. In derselben Gruppe sollten jetzt Original, v1 und v2 erscheinen.

Wähle v2 → Design → All operations → Policy-Codeeditor. Ändere in der kopierten Antwortheader-Policy nur:

<value>v1</value>

in:

<value>v2</value>

Speichere. Prüfe, dass v2 weiterhin dieselbe Backend-URL verwendet und Subscription required aktiviert ist. Änderungen an den eigenen Policies von v2 aktualisieren die Policies von v1 nicht. Eine Version kann später andere Operationen, Antwortformate oder ein anderes Backend nutzen. Hier ist nur die Kennzeichnung im Antwortheader absichtlich unterschiedlich.

Beide Versionen testen

Wähle v1 → Test → GET /pet/findByStatus:

Query parameter:
  status: available
Request header:
  Accept: application/json

Verwende für diesen Administratortest die integrierte all-access subscription des Portals und lasse ihren Schlüssel ausgeblendet. Für diesen Test wird kein Product benötigt; Consumption bietet kein Entwicklerportal. Ein Schlüssel, der nur für die ursprüngliche API gilt, gewährt nicht automatisch Zugriff auf die neuen APIs.

Wähle Send und prüfe alle drei Punkte:

• Die Request URL enthält /petstore/v1/pet/findByStatus.
• Der Antwortstatus lautet 200 OK.
• Die Antwortheader enthalten X-CloudTrips-API-Version: v1.

Wähle nun v2 → Test → GET /pet/findByStatus, verwende denselben Abfrageparameter und Anfrageheader und sende erneut. Erwartet werden 200 OK, eine URL mit /petstore/v2/pet/findByStatus und X-CloudTrips-API-Version: v2.

Wähle abschließend Original → Test und rufe dieselbe Operation auf. Sie sollte unter der URL ohne Versionssegment weiterhin 200 zurückgeben. Den eigenen Versionsheader von v1 und v2 sollte sie nicht enthalten.

API	Gatewaypfad, jeweils gefolgt von ?status=available
Original	/petstore/pet/findByStatus
v1	/petstore/v1/pet/findByStatus
v2	/petstore/v2/pet/findByStatus

Alle drei verwenden deinen Gatewayhost, beispielsweise https://apim-ctgateway-weu.azure-api.net. Aktuell leiten sie an dieselbe Backendoperation weiter. Die Bezeichnungen v1 und v2 leiten bestehende Clients nicht automatisch um und erzeugen keine neuen Backendbereitstellungen.

Falls die Ergebnisse abweichen

• 400 oder 429 aus dem vorherigen Lab: Die Policy der Operation wurde mitkopiert. Setze sie in jeder betroffenen Version mit dem Block aus dem Vorbereitungsschritt zurück.
• v2 liefert den v1-Header: Bearbeite die kopierte Outbound-Policy von v2 und speichere. Prüfe außerdem, ob die Test-URL tatsächlich v2 enthält.
• 404: Behalte das Suffix petstore, die Versionskennungen v1 und v2 und die auf /api/v3 endende Backend-URL bei. Füge die Version nicht in den Operationspfad ein.
• 401: Verwende eine Subscription, die Zugriff auf die getestete API-Version gewährt. Die all-access subscription des Portals deckt die Labversionen ab.

Abschluss

Behalte Instanz und Versionen für weitere API-Übungen. Wenn du nur die Versionen dieses Labs entfernen möchtest, lösche v1 und v2 einzeln und erhalte Original. Das Löschen des gesamten Version Sets kann die darin gruppierten API-Versionen entfernen.

Wenn du mit API Management fertig bist, lösche rg-cloudtrips-apim-test-weu. In einer echten API-Einführung solltest du eine alte Version erst nach der Migration ihrer Clients abschalten.