Richtlinie zu API-Versionierung und Abkündigung

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 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 @<Unix-Sekunden> nach RFC 9745, zum Beispiel Deprecation: @1790812800.
Sunset: das Datum der Entfernung als HTTP-Datum (RFC 8594), 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.