Referenz

Versionierung

Eine Version, v1, unter /v1. Sie wächst nur; nichts darin ändert sich oder verschwindet ohne ein Jahr Vorankündigung.

Was sich in v1 ändern kann

Nur additive Änderungen: neue Routen, neue optionale Anfragefelder, neue Antwortfelder, neue Enum-Werte in Antworten, neue Fehlergründe, neue Webhook-Ereignisse und Nutzlastfelder. Schreiben Sie Clients, die unbekannte Felder ignorieren und unbekannte Enum-Werte tolerieren.

Eine inkompatible Änderung ist eine neue Hauptversion (/v2), die neben v1 bereitgestellt wird.

Abkündigung

Eine Route oder ein Feld kann abgekündigt, nie aber an Ort und Stelle geändert werden. Ab dem Tag der Abkündigung trägt jede Antwort, die es berührt, Deprecation: @<unix seconds> (RFC 9745), Sunset: <HTTP date> (RFC 8594) und einen Link zu ihrem Eintrag im Änderungsprotokoll mit rel="deprecation". Danach funktioniert es noch mindestens 365 Tage.

Protokollieren Sie den Deprecation-Header oder lösen Sie dabei einen Alarm aus, dann erfahren Sie von jeder Abkündigung lange, bevor es darauf ankommt. Jede steht im Änderungsprotokoll.

Webhook-Nutzlasten

Webhook-Nutzlasten sind nach Datum versioniert (heute 2026-09-01). Jeder Endpunkt behält die Nutzlast-Version, mit der er erstellt wurde, sodass eine künftige inkompatible Änderung einer Nutzlast nur Endpunkte erreicht, die sich dafür entscheiden.