Welches Urteil trägt das optionale Feld expiresAt, und welche Aktion folgt?

Kompatibel. Alte Nutzer lesen weiter; die Änderung erscheint als Nebenversion.

Das Lager ändert die Bedeutung von available, das Feld bleibt gleich. Brechen Nutzer?

Ja, als stiller Bruch: Datentyp und Name bleiben, aber die Nutzer deuten den Wert falsch. Ein neues Feld einführen statt das alte umzudeuten.

Ein neuer Statuswert soll ergänzt werden. Wie gehst du vor?

Vorteil: kleine, additive Änderung. Risiko: Nutzer ohne Tolerant Reader brechen an unbekannten Werten. Empfehlung: Nutzer vorab prüfen und die Toleranz im Vertrag festhalten.

MechanikKapitel II · Kommunikation · Baustein 9 von 9

API-Versionierung

API-Versionierung macht Änderungen für bestehende Nutzer planbar. Kompatible Erweiterung, Parallelbetrieb und Ablösung brauchen jeweils klare Regeln.

Von Michael Meierhoff · Meierhoff Systems

Kompatible ÄnderungAlte Nutzer funktionieren unverändert.
Breaking ChangeBestehende Nutzer brechen.
Tolerant ReaderNutzer ignorieren Unbekanntes.

Einordnung

Warum das wichtig ist

Ändert eine Schnittstelle ihre Bedeutung unangekündigt, brechen bestehende Nutzer. Kompatible Erweiterungen und geplante Übergänge halten Änderungen beherrschbar. Der aktuelle Inhalt ist Thema von API-Verträgen.

Dieser Baustein erklärt die Entwicklung bestehender Schnittstellen. Für ihren aktuellen Inhalt siehe API-Verträge.

Auf einen Blick · Zwei Versionen nebeneinander

Alte und neue Clients rufen getrennte Versionen v1 und v2 auf; beide landen im selben Dienst.

Shop-Beispiel · Bruchprüfung

Bricht diese Änderung Nutzer?

Das Lagermodul erweitert die Reservierungsantwort um expiresAt. Später soll das bisherige Feld available von einer Zahl zu einer fachlichen Verfügbarkeitsstufe wechseln.

So liest du das Bild

Kompatible Änderung Das Urteil kompatibel, etwa bei optionalem expiresAt.
Breaking Change Das Urteil bricht Nutzer, etwa beim Entfernen von available.
Tolerant Reader Das Urteil nur mit Tolerant Reader bei neuem Statuswert oder Fehlercode.

Reservierungsantwort des Lagers

kompatibelOptionales Feld expiresAt ergänzen

Alte Nutzer ignorieren das unbekannte Feld und lesen weiter wie bisher.

→ Als Nebenversion veröffentlichen

Wähle eine Änderung; das Bild zeigt, ob bestehende Nutzer brechen und was zu tun ist.

Reservierungsvertrag weiterentwickeln

v1
Bestehender Vertrag
reservationId und available als Zahl
v1.1
Kompatibel ergänzen
optionales expiresAt; alte Nutzer lesen weiter
Übergang
Nutzung beobachten
Bestellung übernimmt expiresAt
v2
Bedeutung ändern
availabilityLevel ersetzt available
Ablösung
v1-Verbraucher beendet
alte Variante nach Nachweis entfernen

Die Zeitleiste trennt die kompatible Ergänzung von der späteren brechenden Umstellung und der Ablösung.

Nutzen & Grenzen

Hilft, wenn

Inkompatible Vertragsänderungen lassen sich mit Versionierung und parallelem Betrieb steuerbar migrieren.
Nutzungsmessung zeigt, welche älteren Konsumenten noch aktiv sind und wann eine Ablösung tragfähig wird.
Eine explizite neue Vertragsversion hält Bedeutungsänderungen von bestehenden Annahmen getrennt.

Grenzen

Parallele Versionen vergrößern Pflege- und Sicherheitsaufwand; Nutzung messen und die Ablösung terminieren.
Additive Änderungen können Bedeutung verändern; prüfe reale Annahmen der Nutzer statt nur die Schema-Kompatibilität.
Die Ablösung braucht Rückfall- und Migrationsplan; Daten migriert Datenmigration, Zusagen sichert API-Verträge.

In der Praxis

Bewerte Änderungen anhand von Schema und Bedeutung und klassifiziere ihre Kompatibilität. Additive Formänderung und semantischer Wechsel brauchen unterschiedliche Migrationswege.
Führe neue Vertragsstände parallel ein und messe Konsumentennutzung. Lege Verantwortliche, Zeitplan und Rückfallmöglichkeit für die Ablösung fest.
Entferne alte Versionen erst nach nachgewiesener Migration. Der Baustein API-Verträge definiert beobachtbares Verhalten; Datenmigration deckt gespeicherte Daten ab.

Ausführliche Erklärung lesen

Versionierung macht inkompatible Änderungen an einem Vertrag explizit und gibt Anbietern wie Konsumenten einen Migrationsweg. Kompatibilität umfasst Datenform und fachliche Bedeutung; ein unveränderter Datentyp garantiert keine unveränderte Zusage.

Additive Erweiterungen erleichtern oft den parallelen Betrieb, während Entfernen oder Umdeuten bestehende Konsumenten brechen kann. Nutzungsmessung zeigt, wann eine ältere Vertragsversion abgelöst werden kann.

API-Verträge benennen das beobachtbare Verhalten, das stabil bleiben soll; Datenmigration behandelt die gesonderte Entwicklung bereits gespeicherter Strukturen.

Semantic Versioning drückt Kompatibilität in der Versionsnummer aus. Der Tolerant Reader ignoriert unbekannte Felder und macht Erweiterungen so unkritisch.

Selbst prüfen

Teste dich in drei Stufen

AblesenIm Bild nachsehen
Welches Urteil trägt das optionale Feld expiresAt, und welche Aktion folgt?
Lösung mit Begründung ansehen
Kompatibel. Alte Nutzer lesen weiter; die Änderung erscheint als Nebenversion.
AnwendenAuf eine neue Lage übertragen
Das Lager ändert die Bedeutung von available, das Feld bleibt gleich. Brechen Nutzer?
Lösung mit Begründung ansehen
Ja, als stiller Bruch: Datentyp und Name bleiben, aber die Nutzer deuten den Wert falsch. Ein neues Feld einführen statt das alte umzudeuten.
BewertenEine Alternative abwägen
Ein neuer Statuswert soll ergänzt werden. Wie gehst du vor?
Lösung mit Begründung ansehen
Vorteil: kleine, additive Änderung. Risiko: Nutzer ohne Tolerant Reader brechen an unbekannten Werten. Empfehlung: Nutzer vorab prüfen und die Toleranz im Vertrag festhalten.

Vertiefen

Diese Bausteine führen die Gedanken dieser Seite weiter.

Quellen

Weiter im Lernpfad

Damit hast du Kommunikation & APIs durchlaufen. Weiter geht es mit Verteilte Systeme.

9 Bausteine

Nächster BereichVerteilte Systeme