API-Versionierung und Abkündigung
Abwärtskompatible REST-API-Änderungen und wie inkompatible Änderungen mindestens 6 Monate vorab mit Deprecation- und Sunset-Headern angekündigt werden.
Die REST-API trägt ihre Hauptversion im Pfad: /api/v1. Innerhalb einer Hauptversion ändert sich die API nur so, dass bestehende Clients weiter funktionieren. Eine Änderung, die einen Client beschädigen könnte, wird mindestens 6 Monate vor ihrem Inkrafttreten angekündigt: in der API-Referenz, im API-Änderungsprotokoll und in den Headern jeder Antwort des betroffenen Vorgangs.
Diese Richtlinie gilt ab dem 2026-10-18. Die Änderungen vor der allgemeinen Verfügbarkeit unterlagen nicht der Ankündigungsfrist. Sie sind im API-Änderungsprotokoll aufgeführt.
Version im Pfad
https://<api-host>/api/v1<api-host>: der Hostname der API.
Eine neue Hauptversion wird unter einem eigenen Pfad wie /api/v2 neben v1 bereitgestellt. v1 bleibt verfügbar, und eine inkompatible Änderung an v1 erfordert weiterhin eine Ankündigung mindestens 6 Monate im Voraus.
Abwärtskompatible Änderungen
Diese Änderungen können in v1 jederzeit vorgenommen werden. Bauen Sie Ihren Client so, dass er weiter funktioniert, wenn sie eintreten:
| Änderung | Was Ihr Client tun muss |
|---|---|
| Ein neuer Vorgang | Nichts. |
| Ein neuer optionaler Abfrageparameter oder Header | Nichts. Anfragen ohne ihn funktionieren wie bisher. |
| Ein neues optionales Feld im Anfragetext | Nichts. |
| Ein neues Feld in einer Antwort | Ignorieren Sie Antwortfelder, die Sie nicht kennen. |
| Ein neuer Wert in einer Aufzählung (Enum) einer Antwort | Behandeln Sie Werte, die Sie nicht kennen, zum Beispiel mit einem Standardzweig. |
| Ein neuer Antwort-Header | Ignorieren Sie Header, die Sie nicht kennen. |
| Gelockerte Validierung, etwa eine größere Maximallänge oder ein höheres Limit | Nichts. |
Inkompatible Änderungen
Diese Änderungen werden an einem Vorgang nie ohne das folgende Abkündigungsverfahren vorgenommen:
- Einen Vorgang oder einen Pfad entfernen.
- Einen Pflichtparameter oder ein Pflichtfeld der Anfrage hinzufügen oder einen optionalen Parameter oder ein optionales Feld zur Pflicht machen.
- Den Typ eines Felds oder eines Parameters ändern.
- Einen Wert aus einer Aufzählung (Enum) einer Anfrage entfernen oder die Validierung verschärfen, etwa durch eine kürzere Maximallänge, ein kleineres Maximum, weniger Elemente oder ein neues Muster.
- Ein Antwortfeld entfernen oder es optional oder nullable machen.
- Einen Erfolgsstatuscode oder einen Medientyp entfernen.
- Einen Token-Bereich verlangen, den der Vorgang vorher nicht verlangt hat, oder Bereiche aus einer Menge entfernen, von der einer genügt.
- API-Tokens und Dienstkontoschlüssel bei einem Vorgang ablehnen, der sie akzeptiert hat, sodass er nur noch in einer Konsolensitzung funktioniert.
So wird eine inkompatible Änderung angekündigt
Mindestens 6 Monate bevor eine inkompatible Änderung in Kraft tritt:
- Der Vorgang wird in der API-Referenz und im OpenAPI-Dokument unter
https://<api-host>/openapi.jsonals abgekündigt markiert. Er hatdeprecated: true,x-deprecation-date, das Datum der Ankündigung, undx-sunset, das früheste Datum, an dem der Vorgang nicht mehr funktionieren kann. Beide Daten haben das Format RFC 3339. - Ein Eintrag im API-Änderungsprotokoll beschreibt die Änderung und was stattdessen zu verwenden ist.
- Jede Antwort des Vorgangs trägt die Header aus der folgenden Tabelle.
| Header | Wert |
|---|---|
Deprecation | Das Datum der Ankündigung: @ gefolgt von der Unix-Zeit in Sekunden (RFC 9745). |
Sunset | Das früheste Datum, an dem der Vorgang nicht mehr funktionieren kann, als HTTP-Datum (RFC 8594). |
Link | Die Adresse des API-Änderungsprotokolls, mit rel="deprecation". |
Deprecation: @1792281600
Sunset: Sun, 18 Apr 2027 00:00:00 GMT
Link: <https://docs.cloud.example/docs/developers/rest-api/changelog/>; rel="deprecation"; type="text/html"In diesem Beispiel wurde der Vorgang am 2026-10-18 abgekündigt und kann nach dem 2027-04-18 nicht mehr funktionieren.
Die Header stehen in jeder Antwort des Vorgangs, auch in Fehlerantworten wie 401, 403 und 429. Protokollieren Sie den Header Deprecation in Ihrem Client oder lösen Sie dafür einen Alarm aus, damit Sie von einer Abkündigung aus den Antworten selbst erfahren.
Nach dem Sunset-Datum
Bis zum Datum in Sunset funktioniert ein abgekündigter Vorgang weiter wie dokumentiert. Nach diesem Datum kann er entfernt oder geändert werden. Der Eintrag im Änderungsprotokoll nennt, was stattdessen zu verwenden ist.
So wird die Richtlinie geprüft
Jede Änderung am öffentlichen API-Vertrag wird automatisch mit dem zuvor veröffentlichten Vertrag verglichen. Ein inkompatibler Unterschied verhindert, dass die Änderung veröffentlicht wird – es sei denn, der Vorgang wurde abgekündigt und sein Sunset-Datum ist verstrichen.