API-Versionierung

APIs leben. Sie wachsen, ändern sich, werden besser. Aber: Clients da draußen rufen weiter die alte API auf – Mobile Apps, die der User nicht updatet, Drittanbieter-Integrationen, automatisierte Skripte. Wenn du eine API änderst, ohne darauf zu achten, brichst du die Apps anderer Leute. Das ist die API-Versionierungs-Frage: wie entwickelst du eine API weiter, ohne deine Konsumenten zu verärgern?

Du kennst aus L3 bereits den groben Überblick über die drei Versionierungs-Strategien. Diese Lektion vertieft das Thema: wann ist eine Änderung „breaking"? Wie versioniert man richtig? Wie kündigt man alte Versionen ab? Welche Anti-Patterns sollte man vermeiden? Versionierung ist eines der wenigen Themen, bei dem die Wahl früh getroffen werden muss – nachträglich umstellen ist sehr teuer.

1) Breaking vs. Non-Breaking Changes

Bevor wir über Versionen reden, müssen wir die Grenze ziehen: was ist eine brechende Änderung, was nicht? Eine Breaking Change ist jede Änderung, die alte Clients zum Scheitern bringt. Eine Non-Breaking Change ist eine Erweiterung, mit der alte Clients problemlos weiterleben.

2) Semantic Versioning (SemVer) – der Quasi-Standard

SemVer ist die etablierte Konvention zur Vergabe von Versionsnummern. Format: MAJOR.MINOR.PATCH, z.B. 2.5.3. Jede Stelle hat eine klare Bedeutung. Klick auf die Zahlen, um zu sehen, was sie bedeuten:

3) Die drei Strategien im Detail

In L3 haben wir sie kurz angerissen – jetzt im Detail mit konkreten Beispielen, Vor- und Nachteilen:

4) Deprecation: alte Versionen abkündigen

Eine neue Version erstellen ist die eine Sache. Aber wie wirst du irgendwann die alte wieder los? Du kannst nicht endlos beide pflegen. Hier hilft Deprecation – ein strukturierter Prozess, der den Konsumenten klar macht: „diese Version verschwindet bald".

Standardisierte Mechanismen für Deprecation-Hinweise: der Deprecation-Header in der Antwort, der den Konsumenten markiert, dass dieser Endpunkt veraltet ist. Optional ein Sunset-Header mit dem konkreten Abschaltdatum. Diese Header sind in RFCs definiert und werden von Tools wie Postman erkannt.

5) Strategien zur Migrationsförderung

Damit Konsumenten überhaupt migrieren, müssen sie es wissen und einen Grund haben. Bewährte Praktiken:

• Migrationsleitfaden veröffentlichen: was ändert sich von v1 zu v2? Mit Code-Beispielen.
• Changelog pflegen: jedes Release mit Datum und Änderungen.
• Deprecation-Header senden: Maschinen-lesbar.
• E-Mail-Benachrichtigungen: an API-Key-Inhaber mehrfach vor EOL.
• Statistiken pflegen: welche Clients nutzen noch v1? Wer? Wie aktiv?
• SDKs aktualisieren: wenn ihr offizielle Client-Libraries habt, diese auf v2 stellen – das migriert die meisten Konsumenten automatisch.
• Kurze EOL-Frist androhen, lang einplanen: „Wir kündigen 6 Monate vorher an" – Wirklichkeit: 12 Monate. So bleibst du höflich und kalkulierst Pufferzeit ein.

6) Anti-Patterns – wie man's nicht macht

7) Migrations-Hilfen für Konsumenten

Wenn du Konsumenten freundlich behandelst, migrieren sie auch schneller. Diese Hilfen sind in der Praxis Gold wert:

• Side-by-Side-Vergleich: Tabelle mit v1-Anfrage vs. v2-Anfrage, v1-Antwort vs. v2-Antwort, Diff-Markierungen.
• Migration-Skripte: kleine Skripte, die typische Client-Konfigurationen umschreiben.
• Backwards-Kompatibilitäts-Layer: dein Server akzeptiert in v2 auch noch alte v1-Felder und übersetzt sie intern (temporär).
• Sandbox: eine Testumgebung mit beiden Versionen, ohne dass Live-Daten betroffen sind.
• Dual-Write-Period: ein Zeitfenster, in dem alle Schreibvorgänge in beide Versionen geschrieben werden – falls jemand zurückrollen muss.

8) Praxis-Beispiele großer APIs

Wie machen es die Großen? Spannend zu beobachten:

• GitHub nutzt URL-Versionierung (api.github.com/v3) und parallel eine GraphQL-API als „v4". Deprecations werden Monate vorher per Header und in Newslettern angekündigt.
• Stripe verwendet Datum-basierte Versionierung über Header (Stripe-Version: 2023-10-16). Praktisch: jede Änderung hat ein Datum, Migrationen sind glasklar zuzuordnen.
• Twilio hat /2010-04-01/ als Datums-Version in der URL – ähnlicher Ansatz wie Stripe, aber in der URL statt im Header.
• Google APIs nutzen oft URL-Versionierung wie youtube/v3, calendar/v3 – einheitlich für jede Sub-API.

9) Klausurrelevante Punkte

• Was ist eine Breaking Change? – Beispiele kennen.
• SemVer-Schema – MAJOR.MINOR.PATCH erklären können.
• Drei Versionierungs-Strategien – URL, Header, Query mit je einem Beispiel.
• Warum versionieren? – Antwort: um alte Clients nicht zu brechen.
• Deprecation-Prozess – wie kündigt man eine alte Version ab?

Zusammenfassung

APIs entwickeln sich weiter – aber alte Clients dürfen nicht brechen. Breaking Change: Änderungen, die alte Clients zum Scheitern bringen (Feld umbenennen, Datentyp ändern, Pflichtfelder ergänzen, Endpunkte entfernen). Non-Breaking: Erweiterungen, die alte Clients ignorieren (optionale neue Felder, neue Endpunkte). Faustregel: „Würde mein alter Client noch funktionieren?" SemVer-Schema: MAJOR (Breaking) . MINOR (neue Features) . PATCH (Bugfix). In APIs meist nur MAJOR in der URL sichtbar. Drei Versionierungs-Strategien: URL-Versionierung (/api/v1/... – Standard, sichtbar), Header-Versionierung (theoretisch sauberer, versteckter), Query-Parameter (selten). Praxis-Empfehlung: URL-Versionierung. Deprecation-Lebenszyklus: v2 launchen → v1 als deprecated markieren (Header Deprecation, Sunset) → 6-12 Monate Übergang → EOL. Anti-Patterns: keine Version ab Tag 1, Version pro Endpunkt, mehrere Strategien mischen, endlos alte Versionen pflegen. Klausur-Fokus: Breaking-Change-Beispiele, SemVer-Schema, drei Strategien, Deprecation-Prozess. Nächste Lektion: Rate Limiting und Throttling.