API Versionierung

Eine API sollte grundsätzlich stabil sein. Erfahren Sie, wann die Versionierung von API Schnittstellen durchaus sinnvoll sein kann und worauf Sie sonst noch dabei achten sollten.

Veröffentlicht: Zuletzt aktualisiert:

Fachartikel, Versicherungswirtschaft

1 Min. Lesezeit
Datennetz als Symbolbild für die API Schnittstellenversionierung

Das Dilemma modularer Systeme

Moderne Softwaresysteme sind typischerweise modular aufgebaut. Ihre einzelnen Teile sind über Schnittstellen miteinander verknüpft und werden oft von unterschiedlichen Teams bereitgestellt. Ihr Lebenszyklus folgt unterschiedlichen Rhythmen. Sie entwickeln sich individuell weiter. Das führt zu einem Dilemma: Wie kann man die Funktionalität eines Teils des Gesamtsystems fortentwickeln, ohne die Stabilität des Ganzen zu gefährden?

In der Vergangenheit wählten Versicherungsunternehmen oft einen „Big Bang“-Ansatz: Alle Komponenten des Gesamtsystems wurden zu definierten Releasezeitpunkten in Gänze ausgetauscht. Die Schnittstellen konnten angepasst werden, ohne dass es zu Interoperabilitätsproblemen durch unterschiedliche Softwarestände kam. Dieser Ansatz trägt jedoch heute nicht mehr (und hat es vielleicht auch niemals wirklich). Der starre Releasezyklus ist unflexibel und wirkt sich oft lähmend aus. Die umfangreichen Rollouts müssen koordiniert werden und sind risikoreich, da alle Teile des Gesamtsystems gleichzeitig ausgetauscht werden. Endgültig an seine Grenzen stößt der Ansatz, wenn externe Partner ins Spiel kommen, die ebenfalls zu definierten Zeitpunkten ihre Systeme umstellen müssten.

Die Lösung: Entkopplung durch API Versionierung

Eine Lösung besteht darin, die API Schnittstellen zwischen den einzelnen Komponenten zu versionieren. Dabei muss auf Auf- und Abwärtskompatibilität geachtet werden: Alte Clients müssen mit neuen Servern umgehen können und umgekehrt.

Versionsnummern

Es bietet sich an, die unterschiedlichen Entwicklungsstände einer API Schnittstelle mit individuellen Versionsnummern zu identifizieren. Etabliert hat sich hierbei das Konzept der semantischen Versionierung.

Im Prinzip besteht dort eine Versionsnummer aus drei Teilen:

x.y.z (Beispiel: 10.7.3)

x bezeichnet dabei die Hauptversion. Eine neue Hauptversion entsteht typischerweise durch inkompatible Änderungen der Schnittstelle.

y steht für die Unterversion. Unterversionen sind im allgemeinen untereinander kompatibel.

z kennzeichnet Fehlerbehebungen.

Inkompatible Änderungen

Der offensichtlichste Bruch der Kompatibilität entsteht, wenn sich die Schnittstelle strukturell ändert. Das kann in einer tiefgreifende Änderung der verwendeten Datenstrukturen oder der angebotenen Operationen begründet sein. Oder es ändert sich sogar die verwendete Basistechnologie, z.B. SOAP/XML in REST/JSON oder ein synchroner Webserviceaufruf in die Befüllung einer asynchronen Messagequeue.

Steht ein Wechsel auf eine neue Hauptversion an, muss der Code für Client und Server meist entweder neu entwickelt oder zumindest stark überarbeitet werden. Um ältere Clients nicht „abzuhängen“, sollte ein Server zumindest für eine gewisse Karenzzeit auch noch die alte Interfaceversion parallel bereitstellen. Die unterschiedlichen Hauptversionen der Schnittstelle können Sie technisch z.B. über unterschiedliche Servicenamen unterschieden.

Kompatible Änderungen

Harmloser erscheinen einfache Erweiterungen von Datenstrukturen. Je nach verwendeter Basistechnologie ergeben sich jedoch auch hier Herausforderungen durch syntaktische oder semantischeÄnderungen. Als Beispiel dient uns ein Webservice, der zu einer ISBN-Nummer den empfohlenen Verkaufspreis eines Buches liefert. In einer Version 1.0.0 wird einfach der Betrag in Euro zurück geliefert. Version 1.1.0 unterstützt auch andere Währungen und liefert zusätzlich zum Preis die passende Währungskennung (EUR, USD etc.).

SOAP-Schnittstellen verwenden oft Verfahren zur XML-Schemaprüfung. Ein Client, der für Version 1.0.0 unserer Preisauskunft konzipiert wurde, wird deshalb das neue Datenfeld für die Währung nicht kennen und eine Fehlermeldung liefern.

REST-Schnittstellen auf JSON-Basis hingegen ignorieren typischerweise unbekannte Datenelemente. Der 1.0.0-Client wird also keine Fehlermeldung liefern. Das klingt zunächst positiv. Wenn er aber vom 1.1.0-Server einen Buchpreis erhält, dessen Währung nicht in EUR angegeben ist, wird der Aufrufer von einem falschen Preis ausgehen.

Dem Server die Schnittstellenversion mitgeben

Eine gängige Lösung des Problems besteht darin, dem Server bei jedem Aufruf auch die API Schnittstellenversion mitzugeben, von der der Client ausgeht. In unserem Beispiel ist das 1.0.0. Der Server kann in seiner Antwort das neue Datenfeld für die Währung unterdrücken. Wurde ein Buch angefragt, dessen Preis in USD vorliegt, kann der Server unterschiedliche Lösungsstrategien implementieren: Entweder er antwortet mit einer Fehlermeldung oder er rechnet den Preis für den Client transparent in Euro um.

Im allgemeinen werden Server häufiger als Clients genutzt. Im Prinzip funktioniert das Verfahren aber auch im umgekehrten Fall. Ein Client in Version 1.1.0 kann anhand einer von einem alten Server in dessen Antworten mitgelieferten Version 1.0.0 erkennen, dass der zurück gelieferte Preis in Euro vorliegt. Im konkreten Beispiel könnte das der Client auch an der fehlenden Währung erkennen. Dies funktioniert aber nicht immer so einfach. Der Grund: Die Anfragen in beiden Schnittstellenversionen umfassen nur die ISBN.  Deshalb kann der Server in unserem Beispiel an den Nutzdaten alleine nicht identifizieren, ob der Client mit Version 1.0.0 oder 1.1.0 der Schnittstelle arbeitet. Es ist daher empfehlenswert, immer mit expliziter Angabe der Schnittstellenversion zu arbeiten.

Ausphasen von API Schnittstellenversionen

Das Vorhalten mehrerer API Schnittstellenversionen kann zu erhöhten Aufwänden führen. Sie sollten also insbesondere vermeiden, mehrere Hauptversionen unbegrenzt lange unterstützen zu müssen. Dafür ist es zum einen empfehlenswert, im Service Level Agreement (SLA) einer Schnittstelle angemessene Fristen für die Abkündigung von Versionen zu vereinbaren. Darüber hinaus sollten Sie überwachen, welche Clients die Schnittstelle in welcher Version aufrufen. Hilfreich ist dabei, den Clients eindeutige Kennungen zuzuordnen, idealerweise in Verbindung mit einem Authentifizierungsverfahren. Anonyme Clients sollten Sie möglichst vermeiden (oder zumindest keinerlei Zusicherungen bzgl. Bereitstellung der Schnittstelle erhalten).

Sie haben Fragen zum Schnittstellenmanagement oder wünschen IT-Beratung? Sprechen Sie uns gerne an.

Autor

Denis Parr – Senior Management Consultant

Denis Parr ist seit über 25 Jahren als Softwareentwickler und Business Analyst tätig. Für die enowa AG unterstützt er Versicherungsunternehmen bei der Konzeption und Entwicklung von Vertriebs- und Bestandssystemen, vorwiegend im Bereich Kraft.
Vertriebsstrategie entwickeln

Veröffentlicht am 16.05.2025

Vertriebsstrategie entwickeln: Der richtige Mix ist das Geheimnis

Was Vertriebsstrategie mit Kochkunst zu tun hat und auf welche Zutaten es wirklich ankommt, damit es am Ende ein Festmahl gibt…

EU AI Act

Veröffentlicht am 14.05.2025

EU AI Act: Was Unternehmen jetzt wissen müssen

Der EU AI Act bringt klare Regeln für den Umgang mit Künstlicher Intelligenz. Unternehmen, die KI einsetzen oder entwickeln, stehen vor neuen Pflichten – und potenziell hohen Strafen. Dieser Artikel zeigt, worauf es jetzt ankommt und wie Sie Ihr Unternehmen…

Momentanreserve Visualisierung Energienetz

Veröffentlicht am 13.05.2025

Momentanreserve: Neue Anforderung – neue Prozesse für Netzbetreiber

Mit dem Beschluss BK6-23-010 schafft die Bundesnetzagentur eine Grundlage für die marktgestützte Beschaffung der sogenannten Momentanreserve. Die Momentanreserve im Stromnetz bezeichnet die sofort verfügbare Energie, die durch die Trägheit rotierender Massen – wie etwa in konventionellen Kraftwerken – bereitgestellt wird.