Letztes Jahr, Maschinenbauer, 180 Mitarbeiter irgendwo zwischen Koblenz und Bonn. Die haben mir stolz ihre "moderne API-Architektur" gezeigt: REST-Endpoints, sauber dokumentiert, gut gemacht. Drei Klicks tiefer kam dann das Eingeständnis: /api/v1, /api/v2, /api/v2_legacy, und irgendwann hatte jemand /api/v3_test deployed, der eigentlich nie produktiv gehen sollte. Der ursprüngliche Entwickler? Seit anderthalb Jahren bei einem anderen Arbeitgeber.
Das ist kein Versagen einzelner Menschen. Das ist das natürliche Endstadium einer Versionierungsstrategie, die als Ausweichmanöver begonnen hat.
Was Milan Jovanović sagt — und er hat recht
Milan schreibt in seinem Artikel "API Versioning Should Be Your Last Resort" etwas, das ich so direkt selten in der Fachwelt lese: Versionierung ist ein Kompatibilitätswerkzeug, keine Design-Strategie. Wer bei jeder Vertragsänderung reflexartig zu /v2 greift, landet mit zwei vollständigen APIs, zwei Dokumentationen und einem Migrationsprojekt, das kein einziger Client freiwillig priorisiert. Sein konkreter Gegenentwurf: vier Regeln für echte Rückwärtskompatibilität — bestehende Felder nie entfernen, nichts Optional-zu-Required machen, die Semantik existierender Operationen nicht verändern, und alles Neue additiv und optional einführen. Das Gegenbeispiel mit dem Soft-Delete, der still zu einem Hard-Delete wird (gleiche URL, gleicher HTTP-Verb, anderes Verhalten — und plötzlich werden Daten unwiederbringlich gelöscht), zeigt genau die Art von Breaking Change, die kein Typchecker und kein Linter findet.
Das ist solide Handwerksarbeit. Ich empfehle den Artikel uneingeschränkt.
Aber.
Wie das im Mittelstand wirklich landet
Milan schreibt aus einer Welt, in der es ein API-Team gibt. Einen Product Owner für die API. Deprecation-Policies mit echten Migrationsfenstern. Telemetrie, die zeigt, welche Clients welche Felder noch nutzen.
In meinen Mandaten — 30 bis 300 Mitarbeiter, produzierendes Gewerbe, Dienstleister, Fachhandel — sieht das anders aus. Dort gibt es einen Entwickler, manchmal zwei, die die API nebenbei betreuen. Die Konsumenten? Das ERP-System, das der Systemhauspartner angebunden hat. Der Shopify-Connector, den eine Agentur mal gebaut hat. Vielleicht noch ein Außendienst-Tool des IT-Dienstleisters.
Drei bis fünf Konsumenten. Keine hundert.
Das verändert die Gleichung fundamental — in beide Richtungen.
Was sich vereinfacht: Wenn du fünf API-Konsumenten hast, brauchst du keine Deprecation-Strategie mit Telemetrie und drei Monate Vorlaufzeit. Du schreibst eine E-Mail. Du rufst an. Du sagst: "In sechs Wochen fliegt das alte total-Feld raus — nutzt ihr das noch?" Bei einem großen Public-API-Anbieter ist das unmöglich. Bei euch ist es ein Anruf am Dienstagvormittag.
Was sich kompliziert: Milans Ansatz setzt voraus, dass irgendwer die vier Regeln kennt, wenn er in sechs Monaten eine neue Anforderung umsetzt. In einem Team, das zwischen Produktionsplanung, ERP-Anbindung und Website-Pflege wechselt, ist dieses institutionelle Gedächtnis oft nicht vorhanden.
Ich habe mehr als einmal erlebt, dass ein Breaking Change nicht aus böser Absicht entstand, sondern weil der Entwickler gar nicht wusste, dass die API extern konsumiert wird. Ein interner Endpunkt, den mal jemand für ein Quick-and-Dirty-Dashboard gebaut hat — und drei Jahre später hängt der Lagerverwaltungs-Connector des Logistikers daran. Niemand hat das je dokumentiert.
Was fehlt — und was ich konkret empfehle
Milans Artikel setzt implizit voraus, dass die API überhaupt dokumentiert ist und dass die Konsumenten bekannt sind. Im Mittelstand ist das keine Selbstverständlichkeit. Bevor ich irgendjemanden über Versionierungsstrategien spreche, stelle ich daher zwei Fragen:
- Wer nutzt diese API — mit Namen und Kontakt?
- Welche Felder werden tatsächlich konsumiert?
Wenn du die nicht beantworten kannst, ist Versionierung nicht dein Problem. Inventur ist dein Problem.
Wenn du diese Fragen beantwortet hast, gilt Milans Ratschlag 1:1: Additive Changes zuerst, Breaking Changes sind immer die letzte Option. Das harte Delete-Beispiel aus seinem Artikel hänge ich in meinen Mandaten gerne aus, weil es das Prinzip "gleiche URL, anderes Verhalten bricht alles" so plastisch zeigt, dass auch der Nicht-Entwickler im Raum es sofort versteht.
Was ich ergänze: Ein schlichtes CHANGELOG.md direkt im Repository, das jede Änderung an der API mit Datum und Grund festhält. Nicht für die Nachwelt — für den nächsten Entwickler, der in zwei Jahren in diesen Code schaut und nicht weiß, warum das deprecated-Feld noch da ist und ob er es jetzt endlich löschen kann. Und: Deprecations aktiv per E-Mail an alle bekannten Konsumenten kommunizieren, nicht passiv per HTTP-Header, den sowieso niemand liest.
Die Versuchung zur Versionierung kommt meistens dann, wenn die Kommunikation vorher gefehlt hat. Wer seine drei Konsumenten kennt und einbezieht, braucht /v2 seltener als gedacht.
Zahlen aus der Praxis
In den letzten vier Mandaten mit einer API-Komponente schätze ich, dass ungefähr 75–80 Prozent der Changes, die als "wir brauchen v2" präsentiert wurden, mit additiven Feldern oder einem Behavior-Flag hätten gelöst werden können. Die restlichen 20 Prozent waren tatsächlich Breaking Changes — aber in keinem einzigen Fall war der Grund technischer Natur. Es war immer, dass die ursprüngliche Semantik eines Felds falsch designed worden war und die Korrektur ohne aktive Konsumenten-Koordination unmöglich schien.
Koordination. Nicht Versionierung. Das ist das eigentliche Problem im Mittelstand.
Der vollständige Original-Beitrag von Milan Jovanović: API Versioning Should Be Your Last Resort
Wenn du gerade eine API-Entscheidung vor dir hast — /v2 oder nicht, Breaking Change oder additiv — und willst das 30 Minuten durchdenken, ohne Verkaufsgespräch:
— Bernhard