API-Änderungsprotokoll
Datierte Änderungen der öffentlichen REST-API, neueste zuerst, mit API-Version, Art der Änderung, betroffenen Vorgängen und den Sunset-Daten von Abkündigungen.
Dieses Änderungsprotokoll listet die Änderungen der öffentlichen REST-API auf, neueste zuerst. Jeder Eintrag nennt sein Datum, die API-Version und die Vertragsversion, die Art der Änderung und die betroffenen Vorgänge. Die Vertragsversion ist die info.version des OpenAPI-Dokuments unter https://<api-host>/openapi.json.
Eine inkompatible Änderung wird hier mindestens 6 Monate vor ihrem Inkrafttreten angekündigt. Die Regeln finden Sie unter API-Versionierung und Abkündigung.
| Art | Bedeutung |
|---|---|
| Hinzugefügt | Ein neuer Vorgang, ein neues Feld, ein neuer Header oder eine neue Funktion. Abwärtskompatibel. |
| Geändert | Geändertes Verhalten. Vor der allgemeinen Verfügbarkeit konnte eine solche Änderung inkompatibel sein. |
| Abgekündigt | Der Vorgang funktioniert bis zu seinem Sunset-Datum weiter und kann danach entfernt oder geändert werden. |
| Entfernt | Der Vorgang oder das Feld wurde nach seinem Sunset-Datum entfernt. |
| Sicherheit | Eine Änderung, die eine Sicherheitslücke schließt. |
2026-10-18
API-Version v1, Vertragsversion 1.4.0.
Abgekündigt
Diese Vorgänge sind abgekündigt. Sunset: 2027-04-18. Ihre Antworten tragen die Header Deprecation, Sunset und Link.
Hinzugefügt
- Die Richtlinie zu Versionierung und Abkündigung der API.
- Die Header
Deprecation,SunsetundLinkin jeder Antwort eines abgekündigten Vorgangs sowie die Felderx-deprecation-dateundx-sunsetbei abgekündigten Vorgängen im OpenAPI-Dokument.
Änderungen vor der allgemeinen Verfügbarkeit
Diese Änderungen wurden vor der allgemeinen Verfügbarkeit vorgenommen und unterlagen daher nicht der Ankündigungsfrist. Sie gelten für die API-Version v1.
| Datum | Art | Änderung |
|---|---|---|
| 2026-10-19 | Geändert | Mit einem API-Token oder einem Dienstkontoschlüssel ist der Header Idempotency-Key nur noch bei Anfragen mit POST erforderlich, die eine Ressource erstellen und mit 202 Accepted antworten. Anfragen mit DELETE, PATCH und PUT sowie Aktionen für bestehende Ressourcen werden wieder ohne den Schlüssel angenommen. Wenn Sie dabei einen Schlüssel senden, gibt eine Wiederholung mit demselben Schlüssel bei den Vorgängen, die den Schlüssel verwenden, weiterhin die erste Antwort zurück. Die API-Referenz führt den Header Idempotency-Key bei den Vorgängen, die ihn ignorieren, nicht mehr auf. |
| 2026-10-19 | Sicherheit | Inkompatible Änderung. Das Erstellen eines Abonnements mit einem API-Token, POST /tenants/{tenantId}/subscriptions, benötigt zusätzlich zu iam:write den Bereich billing:write. Ohne ihn gibt die Anfrage 403 Forbidden mit dem Grund TOKEN_SCOPE_MISSING zurück. Dienstkontoschlüssel werden weiterhin abgelehnt. |
| 2026-10-18 | Sicherheit | Dienstkontoschlüssel haben Bereiche und durchlaufen dieselbe Bereichsprüfung wie API-Tokens. Ein ohne Bereiche erstellter Schlüssel erhält jeden Bereich außer iam:write. Ein Schlüssel kann iam:write nicht haben: Eine solche Anfrage gibt 422 Unprocessable Entity zurück. Vorgänge, die iam:write benötigen, auch die Schreibzugriffe unter /tenants/, lehnen Dienstkontoschlüssel mit 403 Forbidden und dem Code INTERACTIVE_SESSION_REQUIRED ab. |
| 2026-10-18 | Hinzugefügt | Der API-Host stellt unter https://<api-host>/docs einen interaktiven API-Explorer und unter https://<api-host>/openapi.json das OpenAPI-Dokument bereit. |
| 2026-10-18 | Geändert | Listenvorgänge, die alle Elemente zurückgaben, nehmen jetzt page und pageSize an. pageSize liegt bei 1–200, der Standardwert ist 200. Ein größerer Wert gibt 422 Unprocessable Entity zurück. |
| 2026-10-18 | Geändert | Der Server des OpenAPI-Dokuments ist /api/v1 auf dem API-Host. Die veröffentlichte API-Referenz wird nach einer Regel aus dem API-Vertrag erzeugt, die die nicht öffentlichen Vorgänge auslässt. |
| 2026-10-18 | Geändert | Ein Schreibzugriff mit einem API-Token oder einem Dienstkontoschlüssel muss einen Idempotency-Key-Header mitsenden, wenn der Vorgang einen annimmt. Ohne ihn gibt die Anfrage 400 Bad Request mit dem Code IDEMPOTENCY_KEY_REQUIRED zurück. Schlüssel werden pro Mandant geführt, sodass derselbe Schlüssel in zwei Mandanten zwei verschiedene Anfragen bezeichnet. |
| 2026-10-18 | Geändert | Anfragen mit einem API-Token oder einem Dienstkontoschlüssel werden pro Anmeldedaten und pro Mandant begrenzt. Ihre Antworten tragen X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Anfrage über dem Limit gibt 429 Too Many Requests mit dem Code RATE_LIMITED und einem Retry-After-Header zurück. |
| 2026-10-18 | Geändert | Der Katalog der Token-Bereiche hat 17 Bereiche, sodass jeder Teil der API mit einem ausdrücklichen Bereich erreichbar ist. Das OpenAPI-Dokument nennt die Bereiche, die jeder Vorgang benötigt, in x-required-scopes. Das Activity Log akzeptiert iam:read oder audit:read. Ein Token kann kein Token und keinen Schlüssel mit einem Bereich erstellen, den es selbst nicht hat: 403 Forbidden mit details.reason TOKEN_SCOPE_MISSING. Ein Token kann auch kein Token erstellen, das später abläuft als es selbst oder dessen IP-Zulassungsliste nicht innerhalb seiner eigenen liegt: 403 Forbidden mit details.reason TOKEN_FENCE_EXCEEDED. |
| 2026-10-17 | Sicherheit | Das Deaktivieren oder Löschen eines Dienstkontos widerruft seine Schlüssel und die API-Tokens, die es erstellt hat. Das erneute Aktivieren des Kontos stellt sie nicht wieder her. Ein benutzerdefiniertes Ablaufdatum eines API-Tokens darf höchstens 365 Tage in der Zukunft liegen; ein späteres Datum gibt 422 Unprocessable Entity mit details.reason token_lifetime_exceeds_maximum zurück. |
| 2026-10-17 | Hinzugefügt | Ereignisse des Activity Log tragen actorType, das angibt, wie sich der Aufrufer authentifiziert hat: user, api_token, service_account_key oder system. Sie tragen außerdem credentialId, die öffentliche ID des API-Tokens oder Dienstkontoschlüssels, der den Aufruf ausgeführt hat. |