Best Practices zur Versionierung von APIs

Versionierung

Ossi Galkin avatarGeschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contents

Versionierung von APIs

Die Versionierung von Frends-APIs unterscheidet sich von der Versionierung von Prozessen und Unterprozessen, da APIs auf der OpenAPI-Spezifikation (OAS) basieren und normalerweise über die URI versioniert werden. Außerdem hat jede API-Methode ihren eigenen verknüpften Prozess, der die erforderliche Funktionalität bereitstellt, und bei allen Prozessen sind möglicherweise keine Versionserhöhungen erforderlich, wenn sich die OAS ändert. Diese Beziehung zwischen Prozessen und ihrer OpenAPI-Spezifikation sollte beachtet werden, um Kompatibilität und Kontinuität der Versionen in allen API-Lösungen sicherzustellen.

Frends-APIs sollten im OAS und mit der URI versioniert werden, was auch als Routenversionierung bezeichnet wird. Die bewährte Vorgehensweise für die OAS-Versionierung besteht darin, dieselbe semantische Versionierung zu verwenden, die von Prozessen und Unterprozessen verwendet wird. Die URI-Versionierung von APIs sollte mit der Hauptversion von OAS korrelieren.

Unten finden Sie eine OAS für eine Benutzer-API mit der Version 1.0.1, die die URI-Version in der URL /api/users/v1 korreliert. Wenn die Hauptversion von OAS auf 2.x.x erhöht wird, müssen Entwickler eine Kopie dieser API erstellen, die Version auf dem Server erhöhen und die URL-Eigenschaft der OAS in url/api/users/v2 ändern. Diese Erhöhung der Hauptversion erfordert eine neue Instanz der OpenAPI-Spezifikation mit einer neuen Version auf der Server-URL, da die API-Server-URL nach dem ersten Speichern nicht mehr geändert werden kann.

openapi: 3.0.1 Info: Titel: Benutzer-API Beschreibung: Die API zum Abrufen der Benutzer. Version: 1.0.1 Server: - URL: /api/users/v1 Beschreibung: Ausführliche Beschreibung

Beim Aktualisieren der URL für eine Frends-API muss eine neue Spezifikation mit neuen verknüpften Prozessen erstellt werden, da die URL nach dem ersten Speichern nicht mehr geändert werden kann.

Für eine optimale Versionskorrelation zwischen APIs und Prozessen hinter den Methoden wird empfohlen, die Hauptversion des Prozesses auf die gleiche Version wie die OAS zu aktualisieren.

Bei APIs ist es letztlich am wichtigsten, die Dokumentation auf dem neuesten Stand zu halten und die Versionierung als Unterstützung zu nutzen. So wissen Entwickler, welche Version sie verwenden müssen und wie kompatibel die Änderungen wirklich sind.

Der nächste Artikel istBewährte Vorgehensweisen bei der Verwendung von Unterprozessen


Verwandte ArtikelBest Practices zu Versionskonventionen in FrendsBest Practices Semantische Versionierung von FrendsBest Practices zur Versionierung von Prozessen und UnterprozessenEinführung in die Bereitstellung von APIs und die API-VersionskontrolleEinführung in die Verwendung von Unterprozessen in APIs