Unsere REST-API bedient drei mobile Anwendungen, zwei Web-Clients und Partnersysteme. Jeder Client hat einen anderen Deployment-Zyklus. Wir brauchen Versionierung.
Drei Strategien¶
URL-Pfad: /api/v1/projects — am lesbarsten, einfach zu routen.
Header: Accept: application/vnd.core.v2+json — sauberer, aber schwieriger zu testen.
Query-Parameter: ?version=2 — ein Kompromiss.
Wir haben uns für URL-Pfad-Versionierung entschieden — Einfachheit gewinnt.
Breaking vs. Non-Breaking Changes¶
- Breaking: Feld entfernen/umbenennen, Typ ändern → neue Version
- Non-Breaking: Feld hinzufügen, neuer Endpoint, optionaler Parameter → gleiche Version
Das Schlüsselprinzip: so lange wie möglich nur additiv bleiben. Deprecation-Prozess: Sunset-Header, Clients benachrichtigen, 6 Monate Monitoring, dann abschalten.
Versionieren Sie vom ersten Tag an¶
Versionierung nachträglich hinzuzufügen ist schwieriger. Auch mit einem einzigen Client — beginnen Sie mit /api/v1/.
Brauchen Sie Hilfe bei der Implementierung?
Unsere Experten helfen Ihnen bei Design, Implementierung und Betrieb. Von der Architektur bis zur Produktion.
Kontaktieren Sie uns