Versionierung und Kompatibilität

Der öffentliche Partner-Vertrag startet bei 1.0.0 und folgt Semantic Versioning. OpenAPI.info.version, Changelog, Versionsauswahl und unveränderliche Download-Artefakte beziehen sich auf dieselbe Vertragsversion.

Was sich ändern darf

• Patch-Releases korrigieren den Vertrag kompatibel, ohne neue Partner-Operationen einzuführen.
• Minor-Releases ergänzen kompatible Funktionen. Neue Operationen erfordern mindestens ein Minor-Release; additive Schemaänderungen werden zusätzlich auf Integrationsrisiken geprüft.
• Major-Releases enthalten inkompatible Änderungen und verwenden einen neuen URL-Namespace, beispielsweise /api/v2/. Ein bestehender /api/v1/-Vertrag wird nicht stillschweigend gebrochen.
• Rein redaktionelle Änderungen an Leitfäden erhöhen die Vertragsversion nicht. Jede Seite nennt dafür Verantwortliche und Prüfdatum.

Weg zu einer neuen Major-Version

flowchart LR
  accTitle: Kompatibler Weg von API v1 zu einer späteren Major-Version
  V1[Stabiler v1-Vertrag] --> Additive[Kompatible 1.x-Erweiterungen]
  Additive --> Deprecate[Betroffene Funktionen als deprecated markieren]
  Deprecate --> Publish[Migration und Support-Ende veröffentlichen]
  Publish --> Test[Partner testen und migrieren]
  Test --> V2[Neuer v2-Namespace]
  V2 --> Parallel[v1 und v2 im angekündigten Zeitraum]
  Parallel --> Retire[v1 nach veröffentlichtem Support-Ende stilllegen]

Vor einer Major-Version werden Migrationsanleitung und vertragliches Support-Ende veröffentlicht. Eine Stilllegung erfolgt nicht allein aufgrund der Veröffentlichung von v2.

Automatische Kontrollen

Jede Veröffentlichung exportiert OpenAPI zweimal und verlangt byte-identische Ergebnisse. Spectral und ein öffentlicher Sicherheits-Scan prüfen den Vertrag. Ein Diff gegen die unveränderliche Vorversion klassifiziert Änderungen; das SemVer-Gate weist einen zu kleinen Versionssprung ab. Ein Release-Fragment erzeugt anschließend den Partner-Changelog.