API Versionierung ermöglicht es, Änderungen vorzunehmen, ohne den Ausfall von Clients zu riskieren. Sie dient der Verwaltung von Änderungen, wobei alles, was modifiziert werden kann, auch versioniert werden kann – sei es Dokumente, Quellcode oder APIs. Jeder Stand der Änderungen erhält eine eigene Versionsnummer, um gezielt auf bestimmte Versionen zugreifen zu können.

Ein verbreitetes Schema für Versionsnummern ist das Semantic Versioning, bei dem eine Version mit drei Nummern beschrieben wird. Die erste Nummer, die Major-Number, wird erhöht, wenn die neue Version nicht mehr abwärtskompatibel zur vorigen ist. Die nächste, die Minor-Number wird erhöht, wenn sich die Schnittstelle ändert, ohne die Kompatibilität zur vorigen zu brechen. Die letzte Zahl, beschreibt den Patch-Level bei APIs wären das Änderungen, die sich nicht auf die Schnittstelle auswirken z.B. Änderungen der Dokumentation oder von Metadaten.

API Versionierung ist nicht zwingend erforderlich, solange alle Clients ohne viel Aufwand aktualisiert werden können. Sobald jedoch Clients von externen Teams oder Organisationen entwickelt und betrieben werden, ist die Nutzung von Versionierung angebracht, insbesondere wenn diese Anwendungen von der Funktionalität und Verfügbarkeit der Schnittstelle abhängig sind.

Eine Änderung, die dazu führt, dass Clients nicht mehr erfolgreich eine Schnittstelle nutzen können, wird als Breaking Change bezeichnet.

Zur Ermittlung von Änderungen zwischen verschiedenen API-Versionen stehen Tools wie openapi-diff, oasdiff und optic zur Verfügung, die OpenAPI-Beschreibungen vergleichen können. Ein Versionsvergleich liefert einen Bericht zurück, der auch Breaking Changes auflistet.

Im Video erfährst du, was API-Versionierung ist, welche Arten von Änderungen es gibt und wie man APIs versionieren kann. In einer ausführlichen Live-Demo wird gezeigt, wie man mithilfe von OpenAPI eine Schnittstelle versionieren kann. Es werden Best-Practice-Empfehlungen für das Ausschleichen, die Deprecation von APIs sowie für Sunsetting vorgestellt.