Veraltete REST-Endpunkte und Sunset-Termine
OctoMesh verlagert Operationen von REST-Endpunkten auf CK-Methoden, die Sie als typisierte GraphQL-Mutationen aufrufen. Der REST-Endpunkt einer verlagerten Operation funktioniert mindestens bis zu seinem Sunset-Termin weiter; danach darf er unter den Bedingungen der Fensterregel entfernt werden. Diese Seite listet jeden veralteten REST-Endpunkt, die Methode, die ihn ersetzt, und die Termine, damit Sie Ihre Umstellung vor dem Sunset planen können.
Die Fensterregel
Ein REST-Endpunkt ist veraltet, sobald das Release, das ihn abkündigt (seine Welle), zum ersten Mal in eine Produktivumgebung ausgeliefert ist. Sein Sunset — der früheste Tag, an dem der Endpunkt entfernt werden darf — wird noch bekannt gegeben: Es gibt kein festes Zeitfenster; der Sunset-Termin wird entschieden, sobald die Umstellung auf die Methoden umgesetzt ist, auf dieser Seite veröffentlicht und vorab angekündigt.
Das Datum „veraltet seit" wird deshalb beim Rollout gesetzt, nicht beim Bau des Releases; solange es nicht gesetzt ist, steht in
der Tabelle „wird beim Rollout gesetzt". Solange kein Sunset-Termin entschieden ist, steht in der Tabelle „wird noch bekannt
gegeben", und es wird kein Sunset-Header gesendet. Eine Umgebung sendet die Header Deprecation und Sunset ab ihrem ersten
Deployment, nachdem der jeweilige Termin gesetzt ist.
- Bis zum Sunset verhält sich der Endpunkt genau wie bisher: dieselbe Route, dieselben Request- und Response-Bodies und Statuscodes. Nur die unten beschriebenen Response-Header kommen hinzu.
- Der Endpunkt wird in einem Release nach dem Sunset-Datum entfernt, nicht am Datum selbst, und nur, wenn die Aufrufzählung zeigt, dass die eigenen Clients der Plattform umgestellt haben, und die Aufrufer, die sie noch zeigt, direkt informiert wurden (zusätzlich zur Ankündigung der Welle). Die Release Notes dieses Releases nennen ihn.
- Verlagerte Operationen werden in Wellen abgekündigt. Jede Welle trägt ihre Zeilen mit dem Release, das sie abkündigt, in die Tabelle ein; die Release Notes kündigen die Welle an, und die Termine werden hier eingetragen, sobald sie gesetzt oder entschieden sind.
Veraltete Endpunkte
| Service | HTTP-Methode und Route | Ersetzende Methode (GraphQL-Feld) | Veraltet seit | Sunset | Welle |
|---|---|---|---|---|---|
| Identity | PUT {tenantId}/v1/users/{userName}/roles | User.SetRoles (systemIdentityUsers { setRoles }) | 2026-11-08 | wird noch bekannt gegeben | Identity 1 |
| Identity | PUT {tenantId}/v1/users/{userName}/roles/{roleName} | User.AddRole (systemIdentityUsers { addRole }) | 2026-11-08 | wird noch bekannt gegeben | Identity 1 |
| Identity | DELETE {tenantId}/v1/users/{userName}/roles/{roleName} | User.RemoveRole (systemIdentityUsers { removeRole }) | 2026-11-08 | wird noch bekannt gegeben | Identity 1 |
| Identity | POST {tenantId}/v1/users/{userName}/merge | User.Merge (systemIdentityUsers { merge }) | 2026-11-08 | wird noch bekannt gegeben | Identity 1 |
| Identity | POST {tenantId}/v1/users | User.CreateUser (systemIdentityUsers { createUser }) | beim Rollout | wird noch bekannt gegeben | Identity (Passwort) |
| Identity | POST {tenantId}/v1/users/ResetPassword | User.ResetPassword (systemIdentityUsers { resetPassword }) | beim Rollout | wird noch bekannt gegeben | Identity (Passwort) |
| Bot | GET system/v1/jobs?id={jobId} | runtime.operations der Methoden für Backup, Wiederherstellung und Archivdaten (systemBotTenantRepositorys { dump, restore, exportArchiveData, importArchiveData }); für einen Unter-Tenant dieselben Methoden mit einem Benutzer-Token seines übergeordneten Tenants oder des System-Tenants (Administration durch den übergeordneten Tenant) | beim Rollout | wird noch bekannt gegeben | Bot jobs 1 |
| Bot | GET system/v1/jobs/download?id={jobId} | GET {tenantId}/v1/jobs/download?id={jobId} (der downloadPath des Operationsergebnisses) | beim Rollout | wird noch bekannt gegeben | Bot jobs 1 |
| Bot | DELETE system/v1/jobs/{id} | noch kein Ersatz: Eine Operation kann nicht abgebrochen werden (OD-5); dieser Endpunkt bricht einen laufenden Job weiterhin ab, siehe den Hinweis unten | beim Rollout | wird noch bekannt gegeben | Bot jobs 1 |
Umstieg von den Bot-Job-Endpunkten. Die Zuordnung geht nur in eine Richtung: Eine Operation der Methoden für Backup,
Wiederherstellung und Archivdaten trägt die jobId ihres Jobs (in jeder Fortschrittsmeldung, im Ergebnis und in den Job-Fehlern),
aber eine jobId lässt sich nicht als Operation nachschlagen — runtime.operations liest nach operationId oder listet nach
Methode und Zustand. Ein über die REST-Endpunkte gestarteter Job und jede Job-Art ohne Methode (RT-Import und -Export, CK-Import,
Fixup-Skripte, Secret-Sweep) hat keine Operation: Lesen Sie ihn mit GET system/v1/jobs?id={jobId}, das bis zu seinem Sunset
weiter funktioniert. Eine Operation kann nicht abgebrochen werden; einen laufenden Job brechen Sie mit
DELETE system/v1/jobs/{id} und seiner jobId ab.
Unter-Tenants. Ein Administrator eines übergeordneten Tenants, der einen Unter-Tenant über
{childTenantId}/v1/jobs (oder system/v1/jobs) gesichert oder wiederhergestellt hat, ruft dieselben Methoden am
GraphQL-Endpunkt des Unter-Tenants (/tenants/{childTenantId}/graphQl) mit einem Benutzer-Token des übergeordneten
Tenants (oder, bei einem über system/v1/jobs gestarteten Job, des System-Tenants) auf und liest dort deren Operationen; die Regel spiegelt die REST-Regel (direkte Unter-Tenants, der System-Tenant
für jeden Tenant, Rolle TenantManagement im übergeordneten Tenant, keine Client-Credentials-Tokens), siehe
Administration durch den übergeordneten Tenant über CK-Methoden.
Ein Job, der bereits über REST gestartet wurde, hat keine Operation; lesen Sie ihn wie oben mit GET system/v1/jobs?id={jobId}.
Erst ein neuer Aufruf einer Methode liefert eine Operation.
Routen sind relativ zur Basis-URL des Service; {tenantId} ist der Tenant in der Route. „Veraltet seit" und „Sunset" sind
UTC-Tage. Das GraphQL-Feld ist der Pfad unterhalb von mutation { runtime { … } }, siehe
Typisierte Methoden-Mutationen.
Angekündigte Wellen
Derzeit ist keine Welle angekündigt: Jede Operation, die schon über eine Methode läuft und abgekündigt werden soll, steht in der Tabelle oben. Eine künftige Welle steht zuerst hier, ohne Header und Termine, und wandert mit dem Release, das sie abkündigt, in diese Tabelle.
Nicht Teil einer Welle: Die Kontoseiten des Identity Service ({tenantId}/api/manage/…, etwa Passwort ändern und Passwort
setzen) führen ebenfalls die Methoden User.ChangePassword und User.SetPassword aus, bleiben aber, wie sie sind, und werden
nicht abgekündigt.
Die Welle „Bot jobs 1" (Bot Service, Konfigurationsschlüssel RestDeprecation:Waves:BotJobs1) erhält ihr Datum „veraltet seit"
erst, wenn jede Job-Art, die noch über system/v1/jobs berichtet (RT-Import und -Export, CK-Import, Fixup-Skripte, Secret-Sweep),
ebenfalls ein Operation-Handle hat; bis dahin sind die Endpunkte gekennzeichnet und werden gezählt, senden aber keinen
Deprecation- oder Sunset-Header. Ihr Sunset-Termin folgt wie bei jeder anderen Welle der Fensterregel: Er wird
noch bekannt gegeben.
Die Welle „Identity (Passwort)" (Identity Service, Konfigurationsschlüssel RestDeprecation:Waves:IdentityUsersPassword,
Helm-Wert restDeprecation.waves.IdentityUsersPassword) ist eine eigene Welle, weil sie mit einem späteren Release beginnt als
„Identity 1": dem Release, in dem octo-cli und der MCP-Server Benutzer über die Methoden anlegen und Passwörter über sie
zurücksetzen. Ihr Datum „veraltet seit" ist der Tag, an dem dieses Release zum ersten Mal in eine Produktivumgebung ausgeliefert
ist, und wird beim Rollout gesetzt; ihr Sunset-Termin folgt der Fensterregel: Er wird noch bekannt gegeben. Solange
das Datum „veraltet seit" nicht gesetzt ist, antworten die beiden Endpunkte genau wie bisher und ergänzen nur den Link-Header.
.NET-Clients des SDK sehen IIdentityServicesClient.CreateUser und ResetPassword als veraltet (obsolete) und stellen auf
RtUserMethodClient.CreateUserAsync und ResetPasswordAsync um.
Was Sie bei der Umstellung der Identity-Endpunkte wissen sollten:
User.CreateUserundUser.ResetPasswordtransportieren ein Passwort. Über GraphQL antworten sie mitMETHOD_HANDLER_NOT_AVAILABLE, bis der Betreiber sie freischaltet (Methods:Identity:EnablePasswordMethods, siehe Identity-Methoden).User.CreateUserhat keinen Parameter fürresetPasswordOnLogin: Der REST-Endpunkt setzt dieses Flag am neuen Benutzer, nachdem die Methode ihn gespeichert hat; die Methode allein legt den Benutzer ohne das Flag an. Brauchen Sie das Flag, setzen Sie es nach dem Anlegen mitPUT {tenantId}/v1/users/{userName}(siehe REST-Endpunkte für Benutzeranlage und Passwort-Reset).- Der REST-Passwort-Reset schickt dem Benutzer die Passwort-Reset-E-Mail; die Methode
User.ResetPasswordschickt noch keine E-Mail. Die Benachrichtigung der Methode folgt mit einem späteren Release; bis dahin informieren Sie den Benutzer beim Umstieg selbst. - Die Rollen-Methoden betrachten nur die direkten Rollen eines Benutzers. Die REST-Endpunkte behalten ihren Vertrag für eine Rolle, die nur über eine Gruppe gehalten wird, bis sie entfernt werden (siehe REST-Endpunkte für Rollen und Zusammenführen).
Woran Sie einen veralteten Endpunkt erkennen
Jede Antwort eines veralteten Endpunkts trägt diese Header, unabhängig vom Statuscode (auch 400, 401, 403 und 500).
Link wird ab dem Release gesendet, das den Endpunkt abkündigt; Deprecation und Sunset folgen, sobald ihre Termine gesetzt
sind (siehe die Fensterregel); solange der Sunset-Termin noch bekannt gegeben wird, gibt es keinen Sunset-Header:
| Header | Standard | Beispiel | Bedeutung |
|---|---|---|---|
Deprecation | RFC 9745 | Deprecation: @1796083200 | Der Endpunkt ist seit diesem Zeitpunkt veraltet: @ gefolgt von Unix-Sekunden (UTC-Mitternacht des Tages „Veraltet seit"). |
Sunset | RFC 8594 | Sunset: Mon, 01 Mar 2027 00:00:00 GMT | Ab diesem Zeitpunkt darf der Endpunkt entfernt werden (HTTP-Datum). |
Link | RFC 9745 | Link: <https://docs.meshmakers.cloud/…>; rel="deprecation"; type="text/html" | Dokumentation der ersetzenden Methode. |
Link (optional) | RFC 5829 | Link: <https://…>; rel="successor-version" | Die Nachfolge-Operation, wenn eine genannt ist. |
Ein vorhandener Link-Header, etwa für Paging, bleibt erhalten; die Deprecation-Links sind weitere Werte davon. Die Header-Werte
sind Beispiele, nicht die Termine einer echten Welle.
Unsere Empfehlung für eine Integration:
- Header protokollieren. Lassen Sie Ihren HTTP-Client eine Warnung schreiben, wenn eine Antwort
Deprecation,Sunsetoder einenLinkmitrel="deprecation"trägt, mit Route und Sunset-Datum. Dann erfahren Sie von einer Abkündigung aus Ihren eigenen Logs, nicht nur aus den Release Notes. - OpenAPI-Beschreibung prüfen. Das OpenAPI-Dokument des Service (Swagger UI) kennzeichnet eine veraltete Operation als
deprecated(durchgestrichen dargestellt) und ergänzt ihre Beschreibung um „Sunset<Datum>, use<Link>." („Deprecated, use<Link>.", solange das Sunset-Datum nicht gesetzt ist). Generierte Clients machen daraus meist eine Compiler-Warnung. - Vor dem Sunset umstellen. Rufen Sie die ersetzende Methode als GraphQL-Mutation auf; die verlinkte Methodenseite beschreibt ihre Parameter, ihr Ergebnis und ihre Fehlercodes.
Wer einen veralteten Endpunkt noch aufruft
Die Plattform zählt die Aufrufe jedes veralteten Endpunkts je Endpunkt, OAuth-Client-ID und Statusklasse (Metrik
octo.rest.deprecated.calls). Daran sieht der Betreiber, welche Clients vor dem Entfernen eines Endpunkts noch umstellen müssen.
Die Zählung enthält das Routen-Template (zum Beispiel POST /{tenantId}/v1/users), nie eine Tenant-ID, einen Benutzernamen
oder einen Parameter. Die Service-Accounts von Pipelines (octo-pipeline-sa-{adapterRtId}) werden als ein Client gezählt,
octo-pipeline-sa.
Betreiben Sie eine eigene Integration mit eigener Client-ID, erscheinen Ihre Aufrufe unter dieser Client-ID. Über das Entfernen eines Endpunkts nach dem Sunset wird anhand dieser Zählung entschieden: Eigene Clients der Plattform müssen umgestellt sein, und die Aufrufer, die die Zählung noch zeigt, müssen direkt informiert worden sein; diese Information wird getrennt festgehalten, die Zählung zeigt sie nicht.
Siehe auch
- Identity-Methoden — die Methoden der ersten Welle
- Methodendefinitionen — was eine CK-Methode ist
- GraphQL-Abbildung von Methoden — wie man sie aufruft
- API Integration — Authentifizierung und die REST API allgemein