API-Versionierung – wie gehe ich damit um, wenn sich Schnittstellen ändern?

Hallo Daniel, das Thema hatten wir tatsächlich auch mal in einem Modul zu Softwarearchitektur gestreift, also durchaus prüfungsrelevant, zumindest die Konzepte dahinter.

Zu den drei Strategien kurz meine Einschätzung:

• URL-Versionierung (/v1/, /v2/) ist am transparentesten und am einfachsten zu debuggen, weil man sofort sieht, welche Version man anspricht. Nachteil: verletzt eigentlich das REST-Prinzip, dass eine URI eine Ressource identifiziert und nicht eine Version davon.
• Header-Versionierung (z. B. über Accept-Header mit Content-Negotiation) ist "sauberer" im REST-Sinne, aber in der Praxis fummeliger zu testen und für Konsumenten weniger offensichtlich, weil man es nicht in der URL sieht.
• Query-Parameter ist ein Kompromiss, wird aber seltener sauber durchgehalten, weil Parameter oft auch für Filterung genutzt werden und das kollidieren kann.

Da du nur Konsument bist: Eine Adapter-Schicht (manchmal auch Anti-Corruption Layer genannt, aus dem Domain-Driven-Design-Kontext) ist genau der richtige Ansatz. Du bildest die externe API auf ein eigenes internes Modell ab, sodass Änderungen beim Anbieter nur den Adapter betreffen und nicht deine gesamte Anwendung. Stur auf einer Version festnageln funktioniert nur, solange der Anbieter die alte Version nicht abkündigt, das ist also eher riskant als nachhaltig.

Anna hat das mit dem Anti-Corruption Layer schon gut erklärt, kann ich aus der Praxis nur bestätigen. Ich mach das bei meinen Projekten immer so: Ich lege mir DTOs/eigene Klassen an, die mein internes Modell abbilden, und ein Mapping dazwischen, das die rohen API-Responses übersetzt. Der Rest meiner Anwendung sieht nie die Originalstruktur der API, sondern nur mein eigenes Modell. Wenn sich dann beim Anbieter ein Feld umbenennt, muss ich nur im Mapping eine Zeile ändern und nicht durch den ganzen Code suchen.

Was mir zusätzlich hilft: möglichst defensiv parsen. Also nicht stumpf auf jedes Feld zugreifen, sondern prüfen ob es existiert, Defaults setzen, und bei Pflichtfeldern die fehlen lieber einen klaren Fehler werfen als dass irgendwo später ein kryptischer Nullpointer auftaucht. Für dein Praxisprojekt würde ich dir auch empfehlen, dir ein kleines Testset mit Beispiel-Responses anzulegen (als JSON-Dateien), gegen die du deinen Adapter testest. Dann merkst du sofort, wenn sich was geändert hat, ohne live gegen die echte API zu testen.

Zur Versionierung selbst: in der Praxis sieht man oft, dass Anbieter URL-Versionierung nutzen, aber intern nie richtig aufräumen und alte Versionen ewig mitschleppen müssen, weil Kunden nicht migrieren. Ist also auch für den Anbieter nicht spaßfrei.

Kann Anna und Tobi aus eigener Erfahrung nur bestätigen, Anti-Corruption Layer plus defensives Parsen ist bei mir auch Standard geworden, seit ich einmal eine Nacht mit genau so einem "plötzlich fehlt ein Feld"-Problem verbracht habe.

Zur Frage URL vs. Header noch eine praktische Ergänzung, falls das bei euch im Modul auftaucht: Bei URL-Versionierung landet die Versionsinfo quasi fest im Pfad, dein HTTP-Client muss also nur die Basis-URL je nach Version austauschen, das kannst du sogar über eine Konfigurationsvariable steuern. Vorteil: du kannst problemlos parallel gegen v1 und v2 testen, einfach zwei Basis-URLs im Testset.

Bei Header-Versionierung bleibt die URL stabil, aber du musst bei jedem Request den passenden Header mitschicken (z. B. etwas wie Accept: application/vnd.anbieter.v2+json). Das heißt in deinem Adapter baust du dir am besten eine zentrale Stelle, an der dieser Header gesetzt wird, nicht verteilt über den Code. Sonst vergisst man ihn garantiert irgendwo und wundert sich, warum einzelne Requests plötzlich ein anderes Format liefern.

Mein Merksatz dazu: URL-Versionierung ist einfacher zu debuggen (du siehst sofort beim Logging, welche Version lief), Header-Versionierung ist eleganter, aber du brauchst Disziplin beim zentralen Verwalten der Header. Für ein Praxisprojekt würde ich dir aus Gründen der Nachvollziehbarkeit eher zur URL-Variante raten, falls der Anbieter beides anbietet.