Neue Features, aufgeräumte Felder, bessere Performance: Eine API bleibt selten für immer gleich. Gleichzeitig verlassen sich Apps, Frontends oder Partner-Integrationen darauf, dass Antworten stabil bleiben. Genau hier hilft API Versioning: Änderungen werden so eingeführt, dass bestehende Clients weiter funktionieren oder genug Zeit für ein Upgrade bekommen.
Dieser Artikel erklärt die gängigsten Ansätze, wann eine neue Version wirklich nötig ist und wie Teams Versionen so betreiben, dass sie nicht zur Dauerbaustelle werden.
Warum Versionierung bei APIs überhaupt nötig wird
Was „breaking“ in der Praxis bedeutet
Eine Änderung gilt als Breaking Change, wenn ein Client danach nicht mehr wie erwartet arbeiten kann. Das passiert nicht nur bei komplett entfernten Feldern, sondern auch bei scheinbar kleinen Anpassungen:
- Ein Feld wird umbenannt (z. B. firstName statt firstname).
- Ein Datentyp ändert sich (String wird zu Zahl oder Objekt).
- Ein Endpoint liefert plötzlich andere Standardwerte oder filtert anders.
- Pflichtfelder kommen neu dazu, ohne Default.
Wichtig: Auch „nur“ andere Fehlercodes, andere Pagination-Parameter oder strengere Validierung können Clients brechen, wenn diese darauf nicht vorbereitet sind. Wer Pagination überarbeitet, sollte sich zusätzlich mit API Pagination: Page, Cursor und Best Practices beschäftigen.
Versionierung ist kein Ersatz für gute Abwärtskompatibilität
Versionierung ist ein Sicherheitsnetz, aber kein Freifahrtschein. Das Ziel bleibt: so viele Änderungen wie möglich abwärtskompatibel machen (abwärtskompatibel = alte Clients funktionieren weiterhin). Versionierung kommt dann ins Spiel, wenn Abwärtskompatibilität nicht sinnvoll oder nicht realistisch ist.
Strategien für API-Versionen: URL, Header oder Content?
Version in der URL: sichtbar und leicht zu debuggen
Die bekannteste Variante ist URL Versioning, etwa /v1/users und /v2/users. Vorteile: Versionen sind in Logs und Tools sofort sichtbar, und Routing ist meist einfach.
- Pro: klar erkennbar, gut zu testen, leicht zu dokumentieren.
- Contra: Version wird Teil der Ressource (Diskussionspunkt), viele Routen können doppelt gepflegt werden.
Version per Header: sauber, aber weniger greifbar
Hier bleibt die URL gleich, und ein Header steuert die Version, z. B. Accept: application/vnd.example.v2+json. In der Praxis wird das oft als „Media Type Versioning“ umgesetzt.
- Pro: URLs bleiben stabil, Versionierung ist technisch klar getrennt.
- Contra: schwieriger in Browsern zu testen, Fehler durch fehlende Header häufiger, Debugging in Logs oft schlechter.
Version im Response-Format: oft der Start, selten das Ende
Manche Teams versuchen, ganz ohne explizite Version auszukommen, indem Responses flexibel bleiben und Clients tolerant parsen (tolerant = unbekannte Felder ignorieren). Das kann funktionieren, solange Änderungen wirklich kompatibel bleiben. Spätestens beim Entfernen oder Umbenennen wird aber meist eine echte Version nötig.
Wann eine neue Version gerechtfertigt ist (und wann nicht)
Typische Änderungen ohne neue Version
Viele Verbesserungen brauchen keine neue Version, wenn sie sorgfältig gemacht werden:
- Neue optionale Felder hinzufügen.
- Zusätzliche Endpoints ergänzen, ohne bestehende zu verändern.
- Fehlertexte verbessern, solange Codes und Struktur stabil bleiben.
- Performance-Optimierungen, die das Ergebnis nicht verändern.
Änderungen, die fast immer eine neue Version auslösen
- Entfernen von Feldern oder Endpoints.
- Umbenennen von Feldern oder Änderungen an der Response-Struktur.
- Neue Pflichtfelder ohne Default-Verhalten.
- Geänderte Semantik (z. B. ein Status bedeutet plötzlich etwas anderes).
Gerade bei Fehlerformaten lohnt es sich, ein stabiles Schema einzuführen und beizubehalten. Passend dazu: API-Fehler richtig behandeln.
So lassen sich Versionen planen, ohne sich zu verzetteln
Eine einfache Entscheidungs-Hilfe (verschachtelt)
- Ändert sich nur etwas Zusätzliches?
- Ja: kompatibel halten, keine neue Version.
- Nein: weiter prüfen.
- Muss ein Feld/Endpoint entfernt oder umbenannt werden?
- Ja: neue Version oder vorherige Deprecation (Auslaufphase) einplanen.
- Nein: weiter prüfen.
- Ändert sich die Bedeutung eines Feldes oder die Geschäftslogik?
- Ja: neue Version sehr wahrscheinlich.
- Nein: ggf. kompatible Erweiterung möglich.
Deprecation: Änderungen ankündigen, bevor etwas verschwindet
Deprecation (Auslaufphase) bedeutet: Eine alte Variante wird weiter unterstützt, aber als „wird entfernt“ markiert. Das klappt am besten, wenn es klar kommuniziert wird:
- Dokumentation: Endpoints/Felder als „veraltet“ markieren.
- Response-Header oder Response-Feld, das auf die Nachfolge-Version hinweist.
- Changelog: kurze, klare Hinweise mit Migrationspfad.
Wichtig ist Konsistenz: Wer Deprecations ankündigt, sollte auch zuverlässig nach Plan entfernen. Sonst sammelt sich Altlast an, und niemand nimmt Hinweise ernst.
Praktische Umsetzung: Versionen in Code, Tests und Betrieb
Routing und Handler sauber trennen
Bei URL-Versionierung ist ein häufiger Fehler, V1 und V2 „im selben Controller“ mit vielen if-Abfragen zu mischen. Besser: klare Trennung, z. B. eigene Routen/Handler pro Version. So bleibt die Wartung übersichtlich, und Änderungen sind weniger riskant.
In vielen Projekten lohnt sich außerdem ein gemeinsamer Kern (z. B. Services), während nur die API-Schicht (Mapper/Serializer) pro Version abweicht. Das reduziert doppelte Business-Logik.
Schema-Änderungen im Backend sicher einführen
Oft hängen Breaking Changes nicht nur an JSON-Feldern, sondern an Datenbankänderungen. Ein typischer Weg ist ein „Parallelbetrieb“: Neue Spalten/Tabellen werden ergänzt, alte bleiben vorerst bestehen, und erst später wird aufgeräumt. Dazu passt: Database Migrations verstehen.
Tests: Versionen brauchen eigene Vertrags-Checks
Viele Bugs entstehen, weil zwar die neue Version getestet wird, aber die alte unbemerkt kaputtgeht. Hilfreich sind einfache Contract-Tests (Vertrags-Tests = prüfen, ob Response-Form und wichtige Felder stabil bleiben) für jede unterstützte Version. Das muss nicht kompliziert sein: Schon ein kleiner Satz von Requests mit Snapshot-artigen Erwartungen schützt vor Überraschungen.
Kleine Vergleichsbox: Welche Versionierungs-Strategie passt?
| Ansatz | Geeignet wenn … | Typische Stolpersteine |
|---|---|---|
| URL-Version | viele externe Clients, Debugging muss leicht sein | Duplizierte Routen, Versions-Wildwuchs |
| Header/Media-Type | Clients technisch kontrolliert, saubere Trennung gewünscht | Header fehlen, Testen per Browser/Tools umständlich |
| ohne explizite Version | nur additive Änderungen, starke Abwärtskompatibilität | später schwer, „harte“ Änderungen einzuführen |
Konkrete Schritte für den Start (kurz und umsetzbar)
- Festlegen, was in der API als Breaking Change zählt (mit Beispielen).
- Eine Versionierungs-Strategie wählen und dokumentieren (URL oder Header).
- Deprecation-Regeln definieren: Wie wird angekündigt, wie lange unterstützt?
- Pro Version einen minimalen Satz Contract-Tests anlegen.
- Monitoring ergänzen: Welche Versionen werden tatsächlich genutzt?
Häufige Missverständnisse, die in Teams Zeit kosten
„Wir machen einfach jedes Quartal v3, v4, v5 …“
Viele Versionen bedeuten nicht automatisch weniger Risiko. Meist steigt der Aufwand: Dokumentation, Tests, Support und Bugfixes vervielfachen sich. Besser ist, Versionswechsel nur dann zu machen, wenn es wirklich nötig ist – und kompatible Erweiterungen als Normalfall zu behandeln.
„Wir unterstützen alte Versionen unbegrenzt“
Unbegrenzter Support klingt kundenfreundlich, führt aber oft zu Sicherheits- und Wartungsproblemen: Alte Pfade werden nicht mehr wirklich getestet, und neue Features müssen mit Rücksicht auf uralte Clients gebaut werden. Sinnvoller ist ein klarer Lebenszyklus pro Version, der transparent kommuniziert wird.
„Clients können sich schon anpassen“
Selbst wenn ein Team die Client-App kontrolliert, gibt es reale Verzögerungen: Releases müssen durch Stores, Nutzer:innen aktualisieren nicht sofort, und manche Integrationen laufen automatisiert. Versionierung und Deprecation sind deshalb auch intern ein Stabilitätsfaktor.
Wer zusätzlich sicherstellen möchte, dass Änderungen in Teams zuverlässig ankommen, sollte Releases und Pull Requests eng mit klaren Änderungsnotizen verbinden. Für saubere Team-Historie hilft auch: Git Commit Messages schreiben.
Gut gemachtes Semantische Versionierung (SemVer = Versionen wie 1.2.3 mit Regeln für Major/Minor/Patch) kann bei Libraries helfen. Für Web-APIs wird SemVer oft nur als Orientierung genutzt, weil das „Major“-Konzept in der Realität eher über Versionierungs-Strategien (v1/v2) abgebildet wird. Wichtig ist weniger das Format als die Konsequenz: Was bedeutet ein Major-Wechsel konkret, und was nicht?
Wenn die API zudem öffentlich oder für Partner gedacht ist, lohnt sich eine klare Fehler- und Statuscode-Strategie. Sie reduziert Support-Anfragen und macht Migrationen leichter, weil Clients Fehler sauber erkennen können. Mehr dazu: HTTP Statuscodes verstehen.
