API-Versionierung und Abkündigung

Sie sollen Ihre eigenen Skripte, Integrationen und Zendesk-Client-Bibliotheken auf ChaosDesk ausrichten. Diese Seite ist das Versprechen, das dazugehört: was wir ändern dürfen, was nicht und wie viel Vorwarnung Sie bekommen. Sie gilt für die REST-API unter /api, die Zendesk-kompatible API unter /zd/api/v2 und den Webhook-Vertrag. Jede Änderung landet im API-Änderungsprotokoll.

Die Kurzfassung

Vorlauf, bevor etwas entfernt wird	12 Monate
Versionierung der REST-API	Keine in der URL: /api wächst nur
Versionsnummer	info.version in openapi.json, semantisch
Zendesk-kompatible API	Eingefroren auf die dokumentierten Zendesk-Formate
Webhooks	Ganzzahl version in der Payload, pro Webhook festgelegt
Wie eine Abkündigung angekündigt wird	Änderungsprotokoll, Deprecation- und Sunset-Header, deprecated im OpenAPI-Dokument, E-Mail

Eine lebende REST-API, nur additiv

/api ist in der URL nicht versioniert und wird es nicht sein. Stattdessen erweitern wir sie:

• neue Endpunkte,
• neue optionale Query- und Body-Parameter,
• neue Felder in Antworten.

Schreiben Sie Ihren Client so, dass er unbekannte Felder ignoriert, dann sind neue Felder nie ein Problem. Im Gegenzug entfernen wir nie ein Feld, ändern nie den Typ eines Feldes an Ort und Stelle und machen nie einen bestehenden Parameter zur Pflicht.

Die Version, die Sie in einem Fehlerbericht angeben können, ist info.version im OpenAPI-Dokument. Sie ist semantisch: Die Patch-Nummer steigt bei Korrekturen, die Minor-Nummer bei Ergänzungen und die Major-Nummer nur zusammen mit der Regel unten.

Wenn etwas brechen muss

Eine inkompatible Änderung erscheint neben dem alten Format, nie an seiner Stelle. Das neue Format kommt entweder als neues Feld oder unter einem neuen Pfad nur für die betroffenen Ressourcen (/api/v2/<resource>), und das alte funktioniert den ganzen unten genannten Vorlauf weiter. Wir nutzen keinen datumsbasierten Versions-Header: Er vervielfacht das Verhalten pro Endpunkt, und unsere generierten Client-Bibliotheken legen Pfade fest, keine Header.

Die Zendesk-kompatible API ist eingefroren

/zd/api/v2 gibt es, damit für Zendesk geschriebene Clients weiter funktionieren. Das v2 dort ist die Version von Zendesk, nicht unsere. Auf dieser Schnittstelle fügen wir nur Endpunkte und Felder hinzu und ändern nie eine Antwort, die der Client eines anderen Anbieters auswertet. Wir verpflichten uns auf die Formate, die auf der Seite Zendesk-kompatible API dokumentiert sind, und Vertragstests sichern sie bei jedem Build ab. Ändert Zendesk seine eigene API, bleibt unsere wie dokumentiert, und der Unterschied wird im Änderungsprotokoll festgehalten.

Versionen der Webhook-Payload

Jede Webhook-Zustellung und jeder Ping trägt im Umschlag eine Ganzzahl version. Sie ist heute 1 und Teil des öffentlichen Vertrags.

• Ein inkompatibler Umschlag bekommt eine neue Zahl, nie eine Änderung an einer bestehenden.
• Die Version wird pro Webhook-Abonnement gewählt, sodass ein bestehender Webhook den Umschlag behält, für den er gebaut wurde.
• Solange eine Version ausläuft, werden beide über den ganzen Vorlauf zugestellt.
• Ereignistypen sind additiv. Ein Abonnement auf einen Ereignistyp, den Sie nicht kennen, schlägt nie fehl.
• Ändert sich je das Signaturverfahren, kommt die neue Signatur in einem neuen Header, und beide werden während des Vorlaufs gesendet.

12 Monate Vorlauf

Das Entfernen eines Endpunkts, eines Feldes, eines Ereignistyps oder einer Webhook-Umschlagversion von einer der drei Schnittstellen wird mindestens 12 Monate im Voraus angekündigt.

„Angekündigt“ heißt all das, nicht nur das Erste:

1. ein Eintrag unter Abgekündigt im API-Änderungsprotokoll, mit dem geplanten Datum der Entfernung;
2. Deprecation- und Sunset-Antwort-Header (RFC 8594) an den betroffenen Operationen, damit ein Client es sieht, ohne etwas zu lesen;
3. deprecated: true an der Operation oder dem Feld im OpenAPI-Dokument;
4. eine E-Mail an die Workspace-Inhaber und an die Besitzer von API-Tokens, die den Endpunkt in den letzten 90 Tagen aufgerufen haben.

Die Header sehen so aus:

HTTP/1.1 200 OK
Deprecation: Thu, 12 Mar 2026 00:00:00 GMT
Sunset: Fri, 12 Mar 2027 00:00:00 GMT
Link: <https://chaosdesk.io/developers/api-changelog>; rel="deprecation"; type="text/html"

Deprecation ist der Zeitpunkt der Ankündigung, Sunset der früheste Moment, ab dem die Operation nicht mehr antworten kann.

Die einzige Ausnahme ist eine Änderung, die uns ein Sicherheits- oder Rechtsproblem aufzwingt. Dafür gibt es so viel Vorlauf, wie sicher möglich ist, nie weniger als 7 Tage, und immer eine direkte E-Mail sowie einen Eintrag im Änderungsprotokoll.

Was nicht abgedeckt ist

• Die eigenen Endpunkte der Agent-Anwendung (/mobile-api) sind intern für unsere Apps und ändern sich mit ihnen. Bauen Sie nicht darauf; die REST-API hat dieselben Daten.
• Beta-Endpunkte, wo wir sie anbieten, sind im Änderungsprotokoll als Beta markiert und fallen nicht unter die 12-Monats-Regel, bis das Änderungsprotokoll es sagt. Standardmäßig ist nichts Beta: Alles in der API-Referenz ohne Beta-Hinweis fällt unter die volle Richtlinie.
• Verhalten, das schon immer ein Fehler war. Eine Antwort zu korrigieren, die dieser Dokumentation widersprach, ist eine Korrektur und kommt in einem Patch-Release mit Eintrag im Änderungsprotokoll.

Auf dem Laufenden bleiben

• Verfolgen Sie das API-Änderungsprotokoll, in dem jede Änderung zuerst aufgeschrieben wird.
• Generieren oder aktualisieren Sie Ihre Client-Bibliothek, wenn sich die Minor-Nummer der OpenAPI-Version ändert; die Clients werden aus diesem Dokument generiert.
• Protokollieren Sie die Deprecation- und Sunset-Header in Ihrer Integration. Sie sind die früheste maschinenlesbare Warnung, die Sie bekommen.

Entscheidungsprotokoll: ADR 0014, Versionierung von API und Webhooks und die Abkündigungsrichtlinie.