API-Versionierung ohne Chaos: SemVer, Deprecation, Sunset.
API-Versionierung: Ohne Chaos, ohne Kunden zu verlieren
Breaking Changes sind unvermeidbar. Wie man damit umgeht, ist eine strategische Entscheidung.
Was ein "Breaking Change" ist
Alles, was bestehende API-Clients kaputt macht. Einen Pflichtparameter hinzufügen. Eine Antwortstruktur ändern. Einen Endpoint umbenennen oder löschen. Einen Status Code ändern.
Was kein Breaking Change ist: Neue optionale Parameter hinzufügen. Neue Felder in der Response hinzufügen. Neue Endpoints hinzufügen.
Versionierungsstrategien
URL-Versionierung (/v1/, /v2/): Explizit, einfach zu verstehen, einfach zu routen. Standard für die meisten APIs. Nachteil: URL-Vermüllung bei vielen Versionen.
Header-Versionierung (Accept: application/vnd.api.v2+json): Saubere URLs, schwieriger zu testen und zu debuggen. Selten empfohlen für öffentliche APIs.
Query-Parameter (?version=2): Funktioniert, sieht aber nach Hack aus.
Für die meisten Projekte: URL-Versionierung ist pragmatisch und klar.
Deprecation richtig machen
Eine Version nicht einfach abschalten, ohne Vorwarnung. Deprecation-Header in API-Responses setzen. Kunden mit Ablaufdatum informieren (mindestens 6 Monate Vorlauf für breaking changes). Migrations-Guide bereitstellen.
SemVer für APIs
Major-Version = Breaking Change. Minor = Neue Features (rückwärtskompatibel). Patch = Bug Fixes. Diese Logik für API-Versionen zu verwenden hilft Clients, die Risiko-Einschätzung zu machen.
Checkliste API-Versionierung
Versionierungsstrategie dokumentiert
Breaking Change Definition für das Team klar
Deprecation-Prozess definiert (Timing, Kommunikation)
Deprecation-Header in veralteten Endpoints gesetzt
Migrations-Dokumentation für Breaking Changes
API-Versionierungsstrategie entwickeln?
markom.digital hilft bei der Planung und Implementierung von API-Versionierungsstrategien.
