Die Faustregel für kompatible API-Änderungen kennt jeder: nichts entfernen, nichts umbenennen, nur hinzufügen. Sie stimmt für Felder. Für Aufzählungen stimmt sie nicht.
Der Consumer behandelt alle Fälle — und das ist das Problem
Deine API liefert status mit den Werten offen, bestaetigt und storniert.
Jetzt kommt wartet_auf_zahlung dazu. Du hast nichts entfernt, nichts
umbenannt, keinen Typ geändert.
Beim Consumer steht ein switch über die drei bekannten Werte, mit einem
default, der eine Ausnahme wirft — geschrieben von jemandem, der es ordentlich
machen wollte. Genau dieser Code bricht. Der nachlässige Consumer, der unbekannte
Werte einfach durchreicht, überlebt.
Das ist die unangenehme Seite: Sorgfalt auf der Consumer-Seite erhöht die Bruchgefahr. Deshalb steht in der Kompatibilitätsmatrix bei „Aufzählungswert ergänzt” in der Antwortrichtung oft Bruch — und in der Anfragerichtung kompatibel. Kompatibilität hat zwei Richtungen, und wer nur die Antwort prüft, sieht die Hälfte.
Ankündigen, nicht hoffen
Ein neuer Aufzählungswert gehört deshalb behandelt wie eine Änderung, die weh tun kann: vorher ankündigen, den Consumern eine Frist geben, und in der Dokumentation von Anfang an sagen, dass die Liste wachsen darf. Wer das festhält, bevor der erste neue Wert ansteht, muss später niemanden überzeugen.
Prüfen lässt sich das automatisch — genau dafür laufen Contract Tests vor dem Deployment und nicht danach.
Mehr dazu im Seminar
Die vollständige Matrix, Deprecation- und Sunset-Header nach RFC 9745 und
der Weg in die Pipeline stehen im Modul
API-Evolution, Auslieferung und KI-Unterstützung
— mit Video und Kapitelübersicht.
Zum Seminar Moderne API-Entwicklung mit REST, OpenAPI und Contract Testing