--- title: Richtlinie zu API-Versionierung und Abkündigung description: Wie die öffentliche Cargo-Marshal-API versioniert wird, wie eine Route abgekündigt wird, welche Header das ankündigen und die Mindestfrist von 6 Monaten vor der Entfernung. --- Diese Seite ist die Richtlinie zu Versionierung und Abkündigung der [Persistenz-API](/de/overview/persistence-api) unter `/api/v1`. Sie gilt für die REST-API und für das OpenAPI-Dokument unter `/api/v1/spec.json`. ## Versionierung `/api/v1` ist stabil. Innerhalb von `v1` gibt es nur additive Änderungen: neue Routen, neue optionale Eingabefelder, neue Antwortfelder und neue Werte für `code` oder `data.reason` bei einem bestehenden Status. Bauen Sie Clients so, dass sie unbekannte Antwortfelder ignorieren. Eine inkompatible Änderung erscheint unter einer neuen Version, `/api/v2`, und `v1` funktioniert daneben weiter. Als inkompatibel gilt: - Eine Route oder ein Feld entfernen oder umbenennen. - Eine optionale Eingabe zur Pflicht machen. - Einen Typ oder einen Erfolgsstatus ändern. Jede Änderung der Spezifikation wird vor der Auslieferung auf inkompatible Änderungen geprüft. ## Abkündigung Bevor eine Route oder ein Feld entfernt wird, ist sie im OpenAPI-Dokument mit `deprecated: true` markiert. Jede Antwort einer abgekündigten Route, ob erfolgreich oder nicht, trägt: - `Deprecation`: `true` oder das Datum der Abkündigung in der Form `@` nach [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745), zum Beispiel `Deprecation: @1790812800`. - `Sunset`: das Datum der Entfernung als HTTP-Datum ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), zum Beispiel `Sunset: Thu, 01 Apr 2027 00:00:00 GMT`, sobald es feststeht. - `Link: <…>; rel="deprecation"`: die Seite, die die Umstellung erklärt, sobald sie veröffentlicht ist. ## Mindestfrist Das Sunset-Datum liegt mindestens 6 Monate nach der Ankündigung der Abkündigung. Die Route funktioniert bis zu diesem Datum unverändert weiter. ## Was Ihr Client tun sollte - Protokollieren Sie die Header `Deprecation`, `Sunset` und `Link`, damit eine Abkündigung nicht unbemerkt bleibt. - Lösen Sie einen Alarm aus, wenn ein `Sunset`-Datum näher liegt als Ihr Release-Zyklus. - Folgen Sie dem `deprecation`-Link für die Umstellungsschritte. Heute ist keine `v1`-Route abgekündigt.