API-Versionierung: Schnittstellen langlebig halten

APIs sind zur Infrastruktur des digitalen Handels geworden. Laut Gartner integrieren inzwischen über 90 Prozent der neuen Unternehmensanwendungen APIs als Kernkomponente ihrer Architektur (Gartner). Der Markt für API-Management soll von rund 10 Milliarden US-Dollar im Jahr 2025 auf über 100 Milliarden US-Dollar bis 2033 wachsen (Market Data Forecast, 2025). Je mehr Systeme von einer Schnittstelle abhängen, desto teurer wird jede unkoordinierte Änderung.

Das Kernproblem ist die Kopplung zwischen Anbieter und Konsument. Wenn der Shop ein Datenfeld umbenennt, das ein angebundenes ERP-System erwartet, bricht die Verarbeitung -- möglicherweise unbemerkt, bis Bestellungen nicht mehr ankommen. Versionierung löst dieses Problem, indem sie mehrere Stand-der-Technik-Definitionen einer Schnittstelle gleichzeitig bereitstellt: Bestehende Konsumenten arbeiten weiter mit der alten Version, während neue Funktionen in einer neuen Version ausgeliefert werden. Diese zeitliche Entkopplung ist die Grundlage jeder wartbaren Integration und ergänzt die Architekturfragen, die wir im Beitrag zu REST-API versus Middleware behandeln.

Die verbreitetste Strategie ist die URI-Versionierung, bei der die Versionsnummer Teil des Pfads ist, etwa /api/v1/orders und /api/v2/orders. Der grosse Vorteil ist die Sichtbarkeit: Jeder Aufruf macht sofort klar, welche Version genutzt wird. Das vereinfacht Debugging, Logging und das Caching durch Proxies und CDNs, da unterschiedliche Versionen unterschiedliche URLs besitzen.

URI-Versionierung ist auch für Entwicklerinnen und Entwickler am einfachsten zu verstehen und in der Browser-Adresszeile testbar. Die Shopware Store API und Admin API arbeiten mit einem Versionspräfix im Pfad, was sich gut in dieses Modell einfügt. Der Nachteil: Streng genommen sollte dieselbe Ressource unter einer stabilen URL erreichbar sein -- mehrere Versionen derselben Bestellung unter verschiedenen Pfaden widersprechen einer reinen REST-Lehre. In der Praxis überwiegt jedoch meist der Pragmatismus.

Bei der Header-Versionierung bleibt die URL stabil, und die gewünschte Version wird über einen HTTP-Header übermittelt -- entweder über einen eigenen Header wie X-API-Version oder über Content Negotiation im Accept-Header. So bleibt die Ressourcen-URL über alle Versionen hinweg identisch, was der REST-Philosophie näher kommt.

Der Nachteil liegt in der geringeren Sichtbarkeit: Die Version ist in der URL nicht erkennbar, was Debugging und Caching erschwert. Header-basierte Versionierung erfordert ausserdem disziplinierte Clients, die den Header zuverlässig setzen. Vergisst ein Konsument den Header, muss der Server eine sinnvolle Standardversion liefern -- und genau diese Standardwahl wird bei jedem Versionswechsel zur kritischen Entscheidung. Welche Variante passt, hängt von der Konsumentenlandschaft und den Caching-Anforderungen ab.

Ein drittes Modell verwendet Datumsstempel statt fortlaufender Nummern, etwa die Version 2026-06-22. Dieser Ansatz hat sich bei grossen Plattform-APIs bewährt, allen voran bei Stripe, das seine API seit 2011 datumsbasiert versioniert und Abwärtskompatibilität über mehr als ein Jahrzehnt hinweg gepflegt hat (Stripe Engineering Blog). Beim ersten Aufruf wird ein Konto automatisch auf die aktuelle Version festgelegt -- das sogenannte Pinning.

Der Charme dieses Modells liegt im internen Aufbau: Die Kernlogik kennt nur die jeweils neueste Version. Für ältere Versionen sorgen isolierte Transformationsmodule, die eine moderne Antwort schrittweise in das Format älterer Versionen zurückrechnen (Stripe Engineering Blog). So bleibt die Geschäftslogik frei von Verzweigungen für alte Versionen, und neue Funktionen entstehen ohne Rücksicht auf historische Schemata. Für Shop-Schnittstellen mit vielen externen Konsumenten kann dieses Muster ein Vorbild sein, auch wenn es in der Implementierung anspruchsvoller ist.

Semantische Versionierung (SemVer) strukturiert Versionsnummern nach dem Schema MAJOR.MINOR.PATCH. Eine Erhöhung der Major-Version signalisiert Breaking Changes, eine Minor-Version abwärtskompatible Erweiterungen und ein Patch reine Fehlerbehebungen. Dieses Schema kommuniziert die Tragweite einer Änderung allein über die Nummer.

Trotz seiner Klarheit ist SemVer bei APIs weniger verbreitet, als man erwarten würde: Nur 26 Prozent der Teams nutzen semantische Versionierung, sodass die meisten Änderungen verfolgen, ohne deren Auswirkung klar zu kommunizieren (Postman State of the API 2025). Für Schnittstellen empfiehlt sich meist eine Kombination: Die Major-Version landet im URI-Pfad (v1, v2), während Minor- und Patch-Änderungen abwärtskompatibel innerhalb derselben Major-Version ausgeliefert werden. So bleiben Versionspfade stabil, und nur echte Breaking Changes erzwingen einen neuen Pfad.

Die wirksamste Strategie gegen Versions-Wildwuchs ist, Breaking Changes von vornherein zu vermeiden. Das Prinzip der Toleranz fordert, dass ein Konsument unbekannte zusätzliche Felder ignoriert, statt mit einem Fehler zu reagieren. Ein Anbieter kann dann neue Felder hinzufügen, ohne bestehende Clients zu stören. Umgekehrt sollte ein Anbieter Pflichtfelder grundsätzlich nicht nachträglich verschärfen oder Datentypen ändern.

In Integrationsprojekten zahlt sich diese Disziplin direkt aus: Je mehr Änderungen abwärtskompatibel bleiben, desto seltener muss eine neue Hauptversion ausgerollt werden -- und desto seltener müssen Konsumenten migrieren. Eine robuste Fehlerbehandlung in Schnittstellen ergänzt dieses Prinzip, indem sie unerwartete Datenformate auffängt, statt die Verarbeitung abzubrechen.

Keine Version lebt ewig. Irgendwann soll eine alte Schnittstellenversion abgeschaltet werden, um Wartungsaufwand zu senken. Entscheidend ist, dass dies geordnet und mit ausreichend Vorlauf geschieht. Branchenüblich sind Deprecation-Fristen, die eine Ankündigungsphase, eine Migrationsphase und schließlich die Abschaltung umfassen; verbreitet sind Fristen von mehreren Monaten bis zu rund zwei Jahren je nach Tragweite (Gravitee, 2025).

Ein sauberer Deprecation-Prozess folgt mehreren Stufen. Zuerst wird die neue Version veröffentlicht, während die alte als deprecated markiert, aber weiter betrieben wird. Dann werden Konsumenten aktiv informiert und bei der Migration unterstützt. Erst nach Ablauf der Frist erfolgt die Abschaltung, der sogenannte Sunset.

Damit Konsumenten eine bevorstehende Abschaltung nicht übersehen, sollte sie technisch signalisiert werden. Der HTTP-Standard sieht hierfür dedizierte Header vor: Der Deprecation-Header markiert eine Antwort als veraltet, der Sunset-Header nennt das geplante Abschaltdatum. So erfährt jeder Client bei jedem Aufruf maschinenlesbar, dass die genutzte Version ein Ablaufdatum hat.

Ergänzend zu den Headern braucht es einen gepflegten Changelog, der jede Änderung dokumentiert, sowie einen Migrationsleitfaden, der die Unterschiede zwischen den Versionen konkret beschreibt. Klare Kommunikation gilt als zentraler Erfolgsfaktor, da Breaking Changes für abhängige Systeme erhebliche Störungen verursachen können (Redocly, 2025). Wer Deprecation rein per E-Mail oder Dokumentation kommuniziert, riskiert, dass Konsumenten die Frist verpassen -- maschinenlesbare Signale erreichen auch automatisierte Clients.

Eine zunehmend bevorzugte Philosophie ist die API Evolution: Statt für jede Änderung eine neue Version zu erzeugen, wird eine einzige Version möglichst lange gepflegt. Non-Breaking Changes fliessen direkt ein, und nur für echte Breaking Changes entsteht eine neue Version oder ein neuer Endpunkt. Erfolgreiche Plattformen kombinieren dieses Vorgehen mit expliziter Versionierung für die seltenen Fälle, in denen eine inkompatible Änderung unvermeidlich ist (Speakeasy, 2025).

Dieser hybride Ansatz reduziert die Zahl paralleler Versionen deutlich und damit den Wartungsaufwand. Weniger Versionen bedeuten weniger Code-Pfade, weniger Tests und weniger Verwirrung bei Konsumenten. Für Shop-Schnittstellen, die über Jahre stabil laufen sollen, ist das Ziel daher nicht möglichst viele Versionen, sondern möglichst wenige Versionswechsel bei hoher Abwärtskompatibilität.

Damit versehentliche Breaking Changes gar nicht erst in Produktion gelangen, helfen Vertragstests (Contract Testing). Sie prüfen automatisiert, ob eine API ihren dokumentierten Vertrag -- etwa eine OpenAPI-Spezifikation -- weiterhin erfüllt. Aendert sich ein Feldtyp oder verschwindet ein Endpunkt, schlägt der Test bereits in der Entwicklungspipeline an, bevor Konsumenten betroffen sind.

Ergänzend liefert das Monitoring der Versionsnutzung die Datengrundlage für Deprecation-Entscheidungen. Wenn messbar ist, wie viele Konsumenten noch eine alte Version nutzen, lässt sich die Abschaltung fundiert planen statt zu raten. Ein zentrales Middleware-Gateway eignet sich gut, um Versionsnutzung, Fehlerquoten und Latenzen pro Version an einer Stelle zu erfassen. Diese Observability ist die Voraussetzung dafür, alte Versionen abzuschalten, ohne aktive Konsumenten zu überraschen.

In der Praxis der Shop-ERP-Integration treffen mehrere versionierte Welten aufeinander: die Shopware-API, die API des ERP-Systems wie SAP oder Dynamics und gegebenenfalls eine eigene Integrationsschicht. Jede dieser Schnittstellen hat ihren eigenen Versionslebenszyklus, und Updates erfolgen selten synchron.

Hier zeigt sich der Wert einer zwischengeschalteten Integrationsschicht: Sie kapselt die Versionsunterschiede der angebundenen Systeme. Wenn das ERP-System eine neue API-Version veröffentlicht, wird nur der entsprechende Konnektor in der Integrationsschicht angepasst, während der Shop unverändert weiterarbeitet. Diese Entkopplung ist dasselbe Prinzip, das wir im Beitrag zu REST-API versus Middleware ausführlich behandeln -- angewandt auf das Problem divergierender Versionszyklen. Erfahrungsgemäß kommt das dritte oder vierte angebundene System mit eigenem Versionsfahrplan schneller, als die meisten Unternehmen zunächst annehmen (Projekterfahrung).