Zum Inhalt springen
DUST Docs

Anfragekonventionen: Kontext-Header, Fehler, Lokalisierung

Für jeden organisationsbezogenen /api/v1/*-Endpunkt gilt derselbe Anfragevertrag: ein Bearer-Token, zwei Kontext-Header zur Auswahl der Organisation und des Teams, in deren Kontext Sie handeln, JSON-Anfragekörper (für Datei-Uploads wird stattdessen Multipart oder tus verwendet), eine einheitliche Fehlerstruktur und Cursor-Paginierung bei Listenendpunkten. Diese Seite beschreibt den Vertrag; die einzelnen Domänenseiten setzen ihn voraus.

Kontext-Header

Abschnitt betitelt „Kontext-Header“

Fast alles in der DUST API gehört zu einer Organisation und innerhalb dieser zu einem Team. Mit zwei Headern wählen Sie aus, in welchem Organisations- und Teamkontext eine Anfrage ausgeführt wird:

HeaderErforderlichWert
Dust-Ctx-Org-IdJa, bei organisationsbezogenen EndpunktenUUID der Organisation.
Dust-Ctx-Team-IdNeinUUID des Teams. Wird er weggelassen, wird standardmäßig das Stammteam der Organisation verwendet.
Terminal-Fenster
curl -fsS "https://apid.dustid.io/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID"

In der Praxis sind folgende Details wichtig:

  • Headerwerte müssen UUIDs sein; ein fehlerhaft formatierter Wert wird mit 400 INVALID_REQUEST abgelehnt, bevor der Endpunkt ausgeführt wird.
  • Varianten mit dem Präfix X- (X-Dust-Ctx-Org-Id, X-Dust-Ctx-Team-Id und das veraltete Paar) werden als Aliasse akzeptiert.
  • Endpunkte, die einen Kontext erfordern, ihn aber nicht erhalten, schlagen mit den Fehlercodes ORG_ID_REQUIRED oder TEAM_ID_REQUIRED fehl.
  • Einige Endpunkte sind benutzerbezogen und benötigen keinen Kontext — GET /api/v1/me ist das gängigste Beispiel.

Der Kontext ist eine Autorisierungsgrenze

Abschnitt betitelt „Der Kontext ist eine Autorisierungsgrenze“

Die Autorisierung wird für Ihren Benutzer ausgewertet, der in dem durch die Header angegebenen Team handelt. Derselbe Aufruf mit einer anderen Dust-Ctx-Team-Id kann andere Ergebnisse zurückgeben: Was Sie auflisten, lesen und schreiben können, entspricht dem, was dieses Team sehen kann — seine eigenen Datensätze sowie alles, was mit ihm geteilt wurde. Das Senden eines Kontexts, dem Sie nicht angehören, erweitert Ihre Berechtigungen nicht; Anfragen werden anhand Ihrer tatsächlichen Mitgliedschaften geprüft. Datei-, Ordner-, Beziehungs-, Datensatzverknüpfungs-, Baugruppenimport-, Zertifikatsformular-, Fabric-, Aufteilungs-, Auflistungs-, Öffentliche-Seite-, Seitendesign-, Aktivitäts- und Benutzerverzeichnisoperationen erfordern sowohl für Personen als auch für Dienstkonten eine aktuelle Mitgliedschaft im ausgewählten Team und prüfen, ob es zur ausgewählten Organisation gehört. Für den Datensatzverlauf ist zusätzlich die Berechtigung erforderlich, diesen Datensatz anzuzeigen; die Auswahl einer Datensatz-ID gewährt keinen Zugriff. Auch das Erstellen von Datensätzen (einschließlich Massenerstellung) und Vorlagen erfordert eine aktuelle Mitgliedschaft im ausgewählten Team. Mitgliedschaftslisten für Organisationsadministratoren bleiben auf die ausgewählte Organisation beschränkt. Weitere Informationen finden Sie unter Teams und Freigaben.

Lokalisierung

Abschnitt betitelt „Lokalisierung“

Der optionale Header Dust-Ctx-Locale legt die Sprache für servergenerierten, benutzerseitig angezeigten Text fest — am deutlichsten sichtbar bei den message-Zeichenfolgen von Fehlern:

Dust-Ctx-Locale: zh-CN

Unterstützte Gebietsschemata sind de, es, fr, it, ja, pt, en (Standard) und zh-CN. Fehlt der Header, greift der Server auf den Standard-Header Accept-Language und anschließend auf Englisch zurück. Fehler-codes sind stabile Kennungen und werden niemals lokalisiert — verzweigen Sie anhand von code und zeigen Sie message an.

Fehler

Abschnitt betitelt „Fehler“

Fehlgeschlagene Anfragen geben einen JSON-Anfragekörper mit einer einzigen, einheitlichen Struktur zurück:

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to perform this action",
  "status": 401,
  "detail": { }
}
FeldTypBedeutung
codestringStabiler, maschinenlesbarer Fehlercode. Verzweigen Sie anhand dieses Felds.
messagestringFür Menschen lesbare Beschreibung, gemäß Dust-Ctx-Locale lokalisiert.
statusnumberEntspricht dem HTTP-Statuscode.
detailobject (optional)Zusätzlicher Kontext zu diesem Fehler, beispielsweise Einzelheiten zur Validierung.

Codes, auf die Sie frühzeitig stoßen werden:

CodeTypischer StatusWann
INVALID_REQUEST400Fehlerhaft formatierter Anfragekörper, Abfrageparameter oder Header (Validierungsdetails in detail).
UNAUTHORIZED401Fehlender, abgelaufener oder ungültiger Bearer-Token.
FORBIDDEN403Authentifiziert, aber dieser Teamkontext darf diese Aktion nicht ausführen.
NOT_FOUND / NO_DATA_FOUND404In diesem Kontext ist kein entsprechender Datensatz sichtbar.
ORG_ID_REQUIRED / TEAM_ID_REQUIRED400Der Kontext-Header fehlt bei einem kontextbezogenen Endpunkt.
THREAD_DATA_CONFLICT409Konflikt bei optimistischer Nebenläufigkeitskontrolle: Ihre Ansicht des Datensatzes war veraltet.

Jede Antwort enthält außerdem einen x-request-id-Header. Protokollieren Sie ihn und geben Sie ihn an, wenn Sie den Support kontaktieren — damit lässt sich Ihre Anfrage in den Server-Traces eindeutig auffinden.

Fehler und Scanergebnisse ist die vollständige Referenz: alle Fehlercodes, auf die Sie voraussichtlich stoßen werden, mit ihrem Status, die kanonischen Ergebnistabellen für Identifizierung und Verifizierung, Hinweise zu Wiederholungsversuchen sowie Informationen dazu, wie Sie einen Scanbeleg aufbewahren, wenn eine Operation fehlschlägt.

Paginierung

Abschnitt betitelt „Paginierung“

Listenendpunkte (Datensätze, Ordner, Dateien, Ereignisse, Vorlagen, …) verwenden Cursor-Paginierung:

  • Anfrage: die Abfrageparameter pageSize (Seitenlänge) und cursor (undurchsichtige Zeichenfolge aus einer vorherigen Seite). pageSize muss eine Ganzzahl zwischen 1 und 1.000 sein; einige Endpunkte legen einen niedrigeren Höchstwert fest. Lassen Sie den Parameter weg, um den Standardwert des Endpunkts zu verwenden.
  • Endpunkte, die pageIndex verwenden, akzeptieren Ganzzahlen zwischen 0 und 1.000.000. Negative oder gebrochene Paginierungswerte werden abgelehnt.
  • Antwort: das Array der Elemente sowie optionale Cursor-Zeichenfolgen next und prev. Fehlt next, befinden Sie sich auf der letzten Seite.
Terminal-Fenster
# First page
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"


# Follow the cursor
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50&cursor=$NEXT" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"
{
  "threads": [ ... ],
  "next": "eyJjcmVhdGVkQXQiOi...",
  "prev": "eyJjcmVhdGVkQXQiOi..."
}

Cursor sind undurchsichtig — speichern und verwenden Sie sie erneut, aber analysieren Sie sie niemals. Listenendpunkte, die eine Sortierung unterstützen, akzeptieren order (asc/desc) und ein endpunktspezifisches orderCol (für Datensätze: createdAt, updatedAt, name).

Autorisierungsstufen

Abschnitt betitelt „Autorisierungsstufen“

Jede Operation erfordert eine von drei Berechtigungsstufen, und das Pfadpräfix zeigt Ihnen bereits vor dem Lesen eines einzigen Schemas, welche erforderlich ist:

PräfixWer kann sie aufrufen?Hinweise
/api/v1/org/*Organisationsadministratoren — Benutzer mit der Rolle admin (oder owner) in der durch Dust-Ctx-Org-Id angegebenen OrganisationTeamerstellung, Teamaktualisierungen, Mitgliedschaften
/api/v1/connections/*Teamadministratoren — Administratoren des handelnden, durch Dust-Ctx-Team-Id angegebenen TeamsLebenszyklus und Richtungsänderungen von Verbindungen
alles andereMitglieder des Anfragekontexts, sofern für die Operation nichts anderes angegeben istStandardfunktionsumfang

Jede Operation enthält außerdem eine x-required-role-Erweiterung in der OpenAPI-Spezifikation (member, publisher, team-admin oder org-admin) — behandeln Sie diese als maßgebliche Richtlinie für die jeweilige Operation; eine Operation ohne diese Annotation erfordert member. publisher ist keine eigene Stufe, sondern eine Berechtigung innerhalb einer Teammitgliedschaft: Sie ist erforderlich, um die Daten eines Teams öffentlich lesbar zu machen, und Teamadministratoren besitzen sie immer. Der Aufruf einer Operation oberhalb Ihrer Berechtigungsstufe gibt unabhängig von den Nutzdaten 403 FORBIDDEN zurück.

Anfragekörper, IDs und Zeitstempel

Abschnitt betitelt „Anfragekörper, IDs und Zeitstempel“
  • Anfragen verwenden Content-Type: application/json, sofern ein Endpunkt nicht ausdrücklich Multipart-Formulardaten akzeptiert (Kennungsscans unter /api/v1/tags/*, Datei-Uploads).
  • IDs sind UUID-Zeichenfolgen gemäß RFC 4122 (threadId, eventId, Organisations- und Team-IDs, …). Behandeln Sie sie als undurchsichtig.
  • Zeitstempel (createdAt, updatedAt, archivedAt, …) sind UTC-Zeitstempelzeichenfolgen.
  • Schreibvorgänge sind ereignisbasiert: Bei der Änderung eines Datensatzes wird dessen Ereignisverlauf ergänzt, statt vorhandene Daten stillschweigend zu überschreiben — Lesevorgänge wie GET /api/v1/threads/{thread_id} geben { thread, events } zurück.

Siehe auch

Abschnitt betitelt „Siehe auch“
Ein Problem mit der Dokumentation melden