API-Versionierung und Deprecation-Policy

Versionen

Die Major-Version der API ist Teil des URL-Pfads: /api/v1/…. Gegen die Version im Pfad programmieren Sie — Plattform-Releases (v0.29, v0.30, …) ändern den /v1-Vertrag nie.

Die unversionierten /api/…-Routen sind die Legacy-v0-Oberfläche: eingefroren, nur noch Bugfixes, für externe Integratoren nicht mehr dokumentiert. Neue Integrationen starten auf /v1.

Kompatibilität innerhalb einer Major-Version

Innerhalb von /v1 sind nicht-brechend und können in jedem Release passieren:

• neue Antwortfelder,
• neue Endpoints,
• neue optionale Request-Parameter,
• neue Enum-Werte.

Ihr Client MUSS ein tolerant reader sein: unbekannte Felder und Enum-Werte ignorieren statt daran zu scheitern. Das ist eine Vertragsanforderung, keine Empfehlung.

Brechend — und nur in einer neuen Major-Version (/v2): Entfernen oder Umbenennen von Feldern, Typ- oder Semantikänderungen, geänderte Statuscodes oder Fehler-type-Identifikatoren.

Deprecation

Wenn etwas in /v1 als veraltet markiert wird:

• Antworten des betroffenen Endpoints tragen einen Deprecation-Header (RFC 9745) und ein Sunset-Datum (RFC 8594) mindestens 6 Monate in der Zukunft,
• die Deprecation wird im Changelog angekündigt,
• der Endpoint funktioniert bis zum Sunset-Datum weiter; entfernt wird nur mit der nächsten Major-Version.

Beobachten Sie diese Header in Ihrem HTTP-Client und behandeln Sie sie als Frühwarnung, nicht als Ausfall.

Fehler-Taxonomie

v1-Fehler sind application/problem+json mit stabiler type-URI. Der Slug am Ende von type (und die code-Erweiterung, wo vorhanden) sind Teil des Vertrags — verzweigen Sie darauf, nie auf den menschenlesbaren detail-Text, der jederzeit umformuliert oder lokalisiert werden kann.