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 Schnittstellenversionierung

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 weitere Informationen? Sprechen Sie uns gerne an. 

  • Teilen
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.

Ähnliche Beiträge
Versicherungswirtschaft

Sofern die Vermittlung von Versicherungsverträgen durch externe Vertriebspartner erfolgt, erhalten diese für die vermittelten Versicherungsverträge Provisionen. Das Abrechnen und Buchen dieser Provisionen ist dabei oftmals ein komplexes Konstrukt, das hohe Anforderungen an das Bestandsführungssystem des Versicherers stellt. Ein Einblick.

Christoph Scholz, Dr. Claus Ziegler   /   25. November 2021
Versicherungswirtschaft

Blogger und Mathematiker haben auf dem ersten Blick kaum etwas gemeinsam. Lesen Sie hier 5 Gründe, warum Aktuare dennoch gute Blogger sind. Der folgende Beitrag ist zwar mit einem Augenzwinkern geschrieben, hat aber einen wahren Kern.

Evgeni Waldmann   /   19. November 2021
Versicherungswirtschaft

„BiPRO 430? Die haben wir doch bereits umgesetzt!“, heißt es häufig. Hierbei beziehen sich die Versicherer in den meisten Fällen lediglich auf die Unternorm 430.1. In der Norm steckt aber noch sehr viel mehr Potenzial.

Maximilian Würz   /   08. September 2021
Newsletter

Bleiben Sie auf dem Laufenden

In unserem Newsletter berichten wir über Technologien, Methoden und Themen rund um die digitale Transformation in den Branchen Industrie und Versicherungswirtschaft. Darüber hinaus erhalten Sie exklusive Einladungen zu Events und Web-Seminaren.

Melden Sie sich kostenlos und unverbindlich zum Newsletter an.

Wir sind für Sie da!

enowa AG
Kontakt