Das Muster ist immer gleich: Ein Feld wird umbenannt, ein Datumsformat vereinheitlicht, ein Endpunkt zusammengelegt — intern eine Kleinigkeit. Am nächsten Morgen schlagen beim Partner die Bestellimporte fehl, das angebundene CRM synchronisiert leere Datensätze und niemand weiss zunächst, warum. Der Schaden entsteht nicht durch die Änderung selbst, sondern dadurch, dass sie unangekündigt war. Genau dagegen gibt es ein erprobtes Handwerkszeug.
Was eine Änderung zum Bruch macht
Nicht jede Änderung ist gefährlich. Additive Änderungen — ein neues optionales Feld, ein zusätzlicher Endpunkt, ein neuer optionaler Parameter — sind rückwärtskompatibel: Bestehende Clients ignorieren, was sie nicht kennen. Breaking Changes sind alles, was bestehende Annahmen verletzt: Felder entfernen oder umbenennen, Pflichtfelder einführen, Datentypen oder Formate ändern, Fehlercodes umbauen, Paginierung anders sortieren. Die erste Regel lautet deshalb: additive Änderungen jederzeit, Breaking Changes nur mit neuer Version. Wer diese Unterscheidung in jedem Review prüft, hat den grössten Teil des Problems bereits gelöst.
Drei Strategien, eine Version zu transportieren
- URL-Versionierung (/v1/orders): Die Version steht sichtbar im Pfad. Einfach zu routen, einfach zu cachen, im Browser und in Logs sofort erkennbar — der pragmatische Standard.
- Header-Versionierung: Ein eigener Header wie X-API-Version wählt die Variante. Die URLs bleiben stabil, dafür ist die Version in Logs, Caches und beim Debugging unsichtbarer.
- Content-Negotiation: Die Version steckt im Accept-Header als eigener Media-Type. Nach reiner HTTP-Lehre die sauberste Lösung, in der Praxis für Konsumenten am erklärungsbedürftigsten.
Die beste Versionierungsstrategie ist die, die Konsumenten verstehen und testen können. Ein sichtbares /v1 in der URL schlägt im Alltag fast immer die theoretisch elegantere Lösung.
Deprecation-Policy: Abkündigen mit Ansage
Eine alte Version stirbt nicht von allein — sie muss geordnet abgekündigt werden. Dazu gehört eine schriftliche Deprecation-Policy: Wie lange wird eine Version nach Erscheinen der Nachfolgerin noch betrieben (üblich sind sechs bis zwölf Monate), wie werden Konsumenten informiert, was passiert am Stichtag. Technisch unterstützt das der Sunset-Header nach RFC 8594: Er teilt jedem Client maschinenlesbar mit, wann der Endpunkt abgeschaltet wird. Ergänzt um einen Deprecation-Hinweis in der Antwort und ein Monitoring, das zeigt, wer die alte Version noch aufruft, wird aus dem gefürchteten Abschalttag ein planbares Ereignis.
Changelog und Verträge mit Konsumenten
Versionierung funktioniert nur mit Kommunikation. Ein gepflegtes Changelog — pro Version, mit Datum und Migrationshinweisen — ist die günstigste Massnahme mit der grössten Wirkung. Die OpenAPI-Spezifikation gehört dabei ins Repository und wird wie Code behandelt: Jede Änderung läuft durchs Review, automatische Diff-Prüfungen schlagen an, wenn ein Commit versehentlich einen Breaking Change enthält. Wer geschäftskritische Partner anbindet, geht einen Schritt weiter und vereinbart Contract-Tests: Der Konsument hinterlegt, welche Felder und Formate er tatsächlich nutzt, und die Pipeline des Anbieters prüft jede Änderung gegen diese Erwartung — der Bruch fällt dann im Build auf, nicht beim Kunden.
Praxis-Empfehlung für den Mittelstand
Für interne APIs und Anbindungen mit einer Handvoll bekannter Konsumenten braucht es kein Grosskonzern-Regelwerk. Bewährt hat sich ein schlankes Set: Major-Version in der URL, additive Änderungen ohne Versionswechsel, Breaking Changes nur mit neuer Major-Version. Maximal zwei Versionen laufen parallel — jede weitere verdoppelt Test- und Wartungsaufwand. Abkündigungen mit sechs Monaten Vorlauf, per Sunset-Header und per E-Mail an registrierte Konsumenten. Und vor jeder Abschaltung ein Blick in die Zugriffslogs: Erst wenn die alte Version messbar unbenutzt ist, wird der Stecker gezogen.
Eine Schnittstelle, die sich nie ändern darf, blockiert die Weiterentwicklung. Eine, die sich unkontrolliert ändert, zerstört Vertrauen. API-Versionierung ist der Mechanismus, der beides verhindert — mit wenig Aufwand, wenn er von Anfang an eingeplant ist.