Zum Hauptinhalt springen

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​

ServiceHTTP-Methode und RouteErsetzende Methode (GraphQL-Feld)Veraltet seitSunsetWelle
IdentityPUT {tenantId}/v1/users/{userName}/rolesUser.SetRoles (systemIdentityUsers { setRoles })2026-11-08wird noch bekannt gegebenIdentity 1
IdentityPUT {tenantId}/v1/users/{userName}/roles/{roleName}User.AddRole (systemIdentityUsers { addRole })2026-11-08wird noch bekannt gegebenIdentity 1
IdentityDELETE {tenantId}/v1/users/{userName}/roles/{roleName}User.RemoveRole (systemIdentityUsers { removeRole })2026-11-08wird noch bekannt gegebenIdentity 1
IdentityPOST {tenantId}/v1/users/{userName}/mergeUser.Merge (systemIdentityUsers { merge })2026-11-08wird noch bekannt gegebenIdentity 1
IdentityPOST {tenantId}/v1/usersUser.CreateUser (systemIdentityUsers { createUser })beim Rolloutwird noch bekannt gegebenIdentity (Passwort)
IdentityPOST {tenantId}/v1/users/ResetPasswordUser.ResetPassword (systemIdentityUsers { resetPassword })beim Rolloutwird noch bekannt gegebenIdentity (Passwort)
BotGET 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 Rolloutwird noch bekannt gegebenBot jobs 1
BotGET system/v1/jobs/download?id={jobId}GET {tenantId}/v1/jobs/download?id={jobId} (der downloadPath des Operationsergebnisses)beim Rolloutwird noch bekannt gegebenBot jobs 1
BotDELETE 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 untenbeim Rolloutwird noch bekannt gegebenBot 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.CreateUser und User.ResetPassword transportieren ein Passwort. Über GraphQL antworten sie mit METHOD_HANDLER_NOT_AVAILABLE, bis der Betreiber sie freischaltet (Methods:Identity:EnablePasswordMethods, siehe Identity-Methoden).
  • User.CreateUser hat keinen Parameter für resetPasswordOnLogin: 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 mit PUT {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.ResetPassword schickt 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:

HeaderStandardBeispielBedeutung
DeprecationRFC 9745Deprecation: @1796083200Der Endpunkt ist seit diesem Zeitpunkt veraltet: @ gefolgt von Unix-Sekunden (UTC-Mitternacht des Tages „Veraltet seit").
SunsetRFC 8594Sunset: Mon, 01 Mar 2027 00:00:00 GMTAb diesem Zeitpunkt darf der Endpunkt entfernt werden (HTTP-Datum).
LinkRFC 9745Link: <https://docs.meshmakers.cloud/…>; rel="deprecation"; type="text/html"Dokumentation der ersetzenden Methode.
Link (optional)RFC 5829Link: <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:

  1. Header protokollieren. Lassen Sie Ihren HTTP-Client eine Warnung schreiben, wenn eine Antwort Deprecation, Sunset oder einen Link mit rel="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.
  2. 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.
  3. 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​