Versionierung
/v1-Vertrag, eingefrorene Fassungen je Release, Deprecation und Sunset.
Die API ist versioniert (ADR-0097). Die Version steht im Pfad: /v1.
Pfad-Version /v1
- Alle Partner-Endpunkte liegen unter
/v1. - Innerhalb von
/v1sind keine brechenden Aenderungen erlaubt. Ein Bruch wird vor dem Release durch ein automatisiertes Diff (oasdiff) gegen die Spec des letzten Plattform-Tags blockiert. - Additive Aenderungen (neue optionale Felder, neue Endpunkte) sind jederzeit moeglich; Clients muessen unbekannte Felder tolerieren.
Release-Fassungen (CalVer)
Zusaetzlich zur Pfad-Version wird die Doku je Plattform-Release eingefroren. Die
Release-Version folgt dem Schema JJJJ.MM.N (CalVer), z. B. 2026.10.1. Jede
freigegebene Fassung bleibt ueber den Versionsumschalter erreichbar; die zugehoerige
OpenAPI-Spec wird als Release-Asset am Git-Tag platform/<JJJJ.MM.N> abgelegt.
Abhaengigkeit: Die eingefrorenen Fassungen und der Versionsumschalter werden mit
den Release-Assets aus ISSUE-0104 (AP8) und dem Release-Skript verknuepft. Diese
Portal-Fassung zeigt bis dahin die aktuelle /v1-Spec.
Deprecation & Sunset
- Veraltete Felder/Endpunkte werden als deprecated markiert (im Schema und im Changelog), bevor sie entfernt werden.
- Entfernung erfolgt fruehestens mit der angekuendigten Sunset-Frist; betroffene
Antworten koennen
Deprecation- undSunset-Header tragen. - Breaking Changes erscheinen nur in einer neuen Pfad-Version (
/v2), nie in/v1.
Die Liste der Aenderungen steht im Changelog.