API Versionierung

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).