Versionierung
Die Notwendigkeit, Services in mehreren Versionen anbieten zu können, ist bedingt durch die Vielzahl an Service-Nutzern, die bei Änderung an einem Service nicht alle zeitgleich auf die neue Version eines Service umschalten können. Daher ist es notwendig, dass in einem, wenn möglich, kurz zu haltenden Übergangszeitraum mehrere Versionen eines Service parallel betrieben werden können.
Die Versionierung wird auf der Ebene von Services, nicht Service-Operationen ausgeführt, da diese Ebene von ihrer Granularität zu den üblichen fachlichen Änderungen passt.
Es kann vorkommen, dass in einem Systemrelease neue Versionen von mehreren Services ausgeliefert werden.
| Eine Version beschreibt die evolutionäre Weiterentwicklung desselben fachlichen Konzepts. Wird ein anderes fachliches Konzept umgesetzt, ist keine Versionierung, sondern eine neue Schnittstelle erforderlich. |
1. Abwärtskompatibilität
Als Abwärtskompatibilität wird die Verwendbarkeit bzw. Kompatibilität neuerer oder erweiterter Versionen eines Services bzw. einer Nachricht oder eines Events zu den Anwendungsbedingungen einer früheren Version bezeichnet. Diese liegt vor, wenn bestehende Kommunikationsteilnehmer eine neue Version eines Services, einer Nachricht oder eines Events ohne Anpassung ihres Codes oder ihrer Konfiguration weiterhin korrekt nutzen können
| Diese Definition basiert auf dem Wikipedia-Artikel zur Abwärtskompatibilität. |
Abwärtskompatibilität umfasst sowohl technische als auch fachliche Aspekte. Technische Kompatibilität liegt vor, wenn die Struktur und Datentypen weiterhin verarbeitet werden können. Fachliche Kompatibilität liegt vor, wenn die Semantik der Daten unverändert bleibt. Eine Änderung kann technisch kompatibel, aber fachlich inkompatibel sein und stellt in diesem Fall einen Breaking Change dar. Abwärtskompatibilität ermöglicht Übergangszeiträume, in denen sich die Kommunikationsteilnehmer schrittweise an die Änderungen anpassen können, ohne dass es zu Unterbrechungen oder Fehlern in der Kommunikation kommt.
Die Verantwortung für Änderungen und damit für die Abwärtskompatibilität liegt in der Regel beim Provider von Services bzw. beim Producer/Publisher von Nachrichten und Events, da diese die Schnittstelle bzw. das Format der Nachrichten und Events definieren und somit für die Consumer festlegen. Ausnahmen bilden Szenarien, in denen ein Consumer viele Producer/Publisher orchestriert und aus diesem Grund das Format der Nachrichten oder Events vorgibt, zum Beispiel im Bereich Telemetrie oder Protokollierung.
Inkompatible Änderungen (englisch: breaking changes) sind dagegen Änderungen an der Schnittstelle eines Services bzw. am Format einer Nachricht oder eines Events, welche die Anwendungsbedingungen einer früheren Version verletzen. Sie führen zu Fehlern oder Unterbrechungen in der Kommunikation, wenn die Kommunikationsteilnehmer nicht gleichzeitig auf die neue Version wechseln können und müssen daher genau geplant und kommuniziert werden.
1.1. Abwärtskompatible Änderungen
Für die Gewährleistung von Abwärtskompatibilität wird ein tolerantes Verhalten der Kommunikationsteilnehmer vorausgesetzt:
-
Clients bzw. Consumer müssen unbekannte Felder ignorieren können.
-
Server bzw. Producer dürfen bestehende Felder nicht entfernen oder in ihrer Bedeutung verändern.
Bei asynchroner Kommunikation ist Abwärtskompatibilität dann gegeben, wenn bestehende Consumer Nachrichten oder Events weiterhin verarbeiten können, ohne dass Fehlverhalten entsteht.
Diese Grundsätze gelten auch für synchrone Kommunikation. Bei asynchroner Kommunikation ist ein tolerantes Verhalten der Consumer zwingend erforderlich, da Producer und Consumer zeitlich und technisch entkoppelt sind.
Bei synchroner Kommunikation wird Abwärtskompatibilität dadurch erreicht, dass bestehende Service-Nutzende neue Versionen ohne Anpassung weiterhin korrekt nutzen können. Dies setzt insbesondere voraus, dass zusätzliche Felder die Verarbeitung bestehender Clients nicht beeinträchtigen. Die Schnittstelle muss so gestaltet sein, dass bestehende Clients weiterhin funktionieren.
Die folgenden Beispiele stellen häufig vorkommende, abwärtskompatible Änderungen dar.
| Änderungstyp | Auswirkung auf die Kommunikation |
|---|---|
Optionales Feld hinzufügen |
Die Kommunikationsteilnehmer können das Feld bei Bedarf setzen bzw. berücksichtigen. |
Neues Feld mit Standardwert hinzufügen |
Die Kommunikationsteilnehmer können das Feld bei Bedarf mit einem eigenen Wert belegen bzw. berücksichtigen. |
Optionale neue Operation / Nachricht / Event hinzufügen |
Die Kommunikationsteilnehmer können die Operation bei Bedarf aufrufen, bzw. die Nachricht oder das Event produzieren oder konsumieren. |
Zusätzliche Response-Felder |
Die Kommunikationsteilnehmer können zusätzliche Felder ignorieren, sofern sie diese nicht auswerten. |
1.2. Inkompatible Änderungen
Die folgenden Beispiele stellen häufig vorkommende, inkompatible Änderungen (Breaking Changes) dar.
| Änderungstyp | Auswirkung auf die Kommunikation |
|---|---|
Neues Pflichtfeld hinzufügen |
Die Kommunikationsteilnehmer müssen das neue Feld verwenden. Eine Übergangsphase mit einer frühzeitigen Einführung des Feldes als optional kann die Auswirkungen dieses Breaking Changes mindern. |
Feld umbenennen / entfernen |
Die Kommunikationsteilnehmer können Services nicht mehr nutzen oder keine Nachrichten / Event mehr produzieren oder konsumieren. Flexible Validierungen und Verarbeitungslogiken können die Auswirkungen eines solchen Breaking Changes mindern. |
Typ oder Semantik eines Felds ändern |
Werte werden von den Kommunikationsteilnehmern falsch interpretiert oder führen zu Konvertierungsfehlern, auch wenn die Struktur gleich bleibt. Diese Änderungen sollten vermieden werden, da sie schwer zu kommunizieren und zu behandeln sind. Stattdessen sollte ein neues Feld eingeführt und das alte Feld zu einem späteren Zeitpunkt entfernt werden. |
Änderung des Fehlerverhaltens oder von Statuscodes |
Die Kommunikationsteilnehmer können auf unerwartete Fehler reagieren oder bestehende Fehlerbehandlungen greifen nicht mehr. |
2. Entscheidungsmodell zur Versionierung
Aufbauend auf der Definition der Abwärtskompatibilität legt die Referenzarchitektur ein verbindliches Entscheidungsmodell für die Versionierung von REST-Services sowie die Versionierung von Nachrichten und Events fest.
Auslöser für eine Versionierung ist stets eine Änderung an einer spezifizierten Nachbarsystemschnittstelle, oder eine technische Änderung wie zum Beispiel ein Update einer Produkt- oder Protokollversion.
Das Entscheidungsmodell zeigt auf, unter welchen Bedingungen:
-
eine bestehende Schnittstelle erweitert werden sollte,
-
eine neue Version der Schnittstelle bereitzustellen ist,
-
ein neuer Kanal erforderlich ist, oder
-
ein neues Backend sinnvoll ist.
Das Entscheidungsraster für die Versionierung von REST-Services, Nachrichten und Events zeigt in Kürze auf, welche Maßnahmen bei welchen Änderungen an REST-Services, Nachrichten und Events zu ergreifen sind, und verweist für weiterführende Informationen auf die entsprechenden Kapitel.
| Kommunikationsmuster | Änderungstyp | Empfohlene Maßnahme |
|---|---|---|
REST-Service |
abwärtskompatibel |
|
REST-Service |
nicht abwärtskompatibel |
|
Nachricht / Event |
abwärtskompatibel |
|
Nachricht / Event |
nicht abwärtskompatibel |
Neuen Nachrichten- / Event-Typ auf neuem Kanal bereitstellen |
2.1. Abwärtskompatible Änderungen
Ist eine Änderung abwärtskompatibel, so wird die bestehende Schnittstelle erweitert. Dies bedeutet:
-
keine neue Service-Version,
-
kein neuer Kanal,
-
kein neues Backend.
Abwärtskompatible Änderungen führen zu einer kompatiblen Weiterentwicklung eines REST-Services beziehungsweise von Nachrichten und Events, um unnötige Parallelität und Versionsvielfalt zu vermeiden.
2.2. Inkompatible Änderungen an REST-Services
Ist eine Änderung an einem REST-Service nicht abwärtskompatibel, so ist eine neue Service-Version bereitzustellen. Die Ausgestaltung der neuen Service-Version ist abhängig von Umfang und Art der Änderungen. Die bestehende Version bleibt für einen Übergangszeitraum parallel verfügbar, sofern bestehende Service-Nutzende nicht zeitgleich migriert werden können.
2.3. Inkompatible Änderungen an Nachrichten und Events
Ist eine Änderung an einer Nachricht oder einem Event nicht abwärtskompatibel, so ist ein neuer Nachrichten- oder Event-Typ auf einem neuen Kanal bereitzustellen. Dieser Kanal ist für die entsprechenden neuen Versionen der Consumer vorgesehen.
3. Lifecycle und Deprecation von Versionen
Jede neue nicht abwärtskompatible Version muss eine Deprecation-Policy für die Vorgängerversion definieren.
Diese umfasst mindestens:
-
Datum der Einführung der neuen Version,
-
Datum der Deprecation der alten Version,
-
Mindestunterstützungszeitraum,
-
geplantes Abschaltdatum,
-
betroffene Clients bzw. Consumer,
-
Migrationsanleitung,
-
technische Metrik zur Nutzung der alten Version.
Die alte Version darf erst abgeschaltet werden, wenn alle betroffenen Service-Nutzenden bzw. Consumer migriert sind. Das Monitoring muss die erfolgreiche Migration bestätigen und Retention-, Replay- sowie weitere relevante Fristen müssen berücksichtigt sein.