Was ein Breaking Change tatsaechlich ist, und wie sich Versionen sauber deprecaten lassen.
Ein Breaking Change ist alles, was bestehende API-Clients kaputt macht: ein neuer Pflichtparameter, eine geaenderte Antwortstruktur, ein umbenannter oder geloeschter Endpoint, ein geaenderter Status Code. Kein Breaking Change dagegen: neue optionale Parameter, neue Response-Felder, neue Endpoints.
Versionierungsstrategien im Vergleich
URL-Versionierung ist explizit, einfach zu verstehen und einfach zu routen, der Standard fuer die meisten APIs, wenn auch mit dem Nachteil zunehmender URL-Vielfalt bei vielen Versionen. Header-Versionierung haelt URLs sauber, ist aber schwieriger zu testen und zu debuggen, weshalb sie fuer oeffentliche APIs selten empfohlen wird. Eine Versionsangabe als Query-Parameter funktioniert, wirkt aber improvisiert. Fuer die meisten Projekte ist URL-Versionierung der pragmatischste Weg.
Deprecation richtig gestalten
Eine Version nicht einfach ohne Vorwarnung abschalten. Ein Deprecation-Header in den Responses, eine Information der Kunden mit Ablaufdatum, mindestens sechs Monate Vorlauf bei Breaking Changes, und ein bereitgestellter Migrations-Guide gehoeren dazu.
Semantic Versioning fuer APIs
Major fuer Breaking Changes, Minor fuer neue, rueckwaertskompatible Features, Patch fuer Bugfixes, dieselbe Logik wie bei Software allgemein hilft Clients, das Risiko einer Aenderung einzuschaetzen.
Checkliste: Versionierungsstrategie dokumentiert, Breaking-Change-Definition im Team klar, Deprecation-Prozess mit Timing und Kommunikation definiert, Deprecation-Header in veralteten Endpoints gesetzt, Migrationsdokumentation vorhanden.
Ein Beispiel aus der Praxis
Ein Anbieter fuehrte eine Breaking Change ein, ohne die betroffenen Partner vorab zu informieren, in der Annahme, die Aenderung sei „nur eine kleine Umbenennung“. Mehrere externe Integrationen brachen daraufhin ohne Vorwarnung, was zu dringenden Supportanfragen und Vertrauensverlust fuehrte. Seit diesem Vorfall gilt eine feste Sechs-Monats-Regel fuer jede Breaking Change, inklusive Deprecation-Header in den betroffenen Responses, die Partnerentwickler automatisch auf die anstehende Aenderung hinweisen, lange bevor sie tatsaechlich greift.
API-Versionierungsstrategie entwickeln? markom.digital hilft bei der Planung und Implementierung von API-Versionierungsstrategien.
