Die Zugriffs-API¶

Diese Seite richtet sich an alle, die eine eigene Anwendung auf OS aufbauen und wissen wollen, was die angemeldete Person darf, damit die Anwendung nur Schaltflächen und Menüs zeigt, die funktionieren. Sie zeigt, wie Sie eine Anfrage an OS stellen, wie Sie pro Art von Ding lesen, was jemand darf, und was allowed_actions an jedem Ding bedeutet. Was Rollen und Regeln sind, steht unter Rollen und Zugriff.

Eine Anfrage an OS¶

• Adresse. Jede Route über eine Organisation liegt unter /api/v1/organisations/{id}, mit der ID der Organisation (org_...).
• Anmeldung. Jede Anfrage trägt das Zugriffstoken der angemeldeten Person: Authorization: Bearer <token>. OS entscheidet für diese Person, in dieser Organisation.
• Listen kommen seitenweise: limit (höchstens 200, Standard 50) und cursor. Eine Antwort hat items und, wenn es mehr gibt, next_cursor. Eine Liste zeigt nur, was die Person sehen darf, eine Seite kann also weniger Zeilen als limit haben, während next_cursor trotzdem weitergeht.
• Versionen. Ein Ding, das Sie als Ganzes ersetzen (eine Gruppe, eine eigene Rolle, ein Attribut, das Regeldokument), trägt version und den Header ETag. Eine Änderung nennt diese Version in If-Match; hat sich das Ding inzwischen geändert, antwortet OS 409.
• Fehler sind application/problem+json:

{"type": "about:blank", "title": "Forbidden", "status": 403,
 "detail": "You may grant only what you hold yourself; you do not hold the role org-admin.",
 "request_id": "..."}

Ein 422 hat zusätzlich errors, eine Liste mit field, message und type pro Feld.

Was jemand darf, pro Art¶

curl -s "$OS/api/v1/organisations/$ORG/access" -H "Authorization: Bearer $TOKEN"

{"organisation_id": "org_...",
 "kinds": [
   {"kind": "organisation", "actions": ["see"]},
   {"kind": "membership", "actions": ["see", "write"]},
   {"kind": "group", "actions": ["see", "write"]},
   ...
 ],
 "core_kinds": [
   {"kind": "model", "actions": ["see", "use"]},
   {"kind": "thread", "actions": ["see", "write", "delete"]},
   ...
 ]}

kinds nennt jede Art von OS und core_kinds jede Art der KI-Funktionen, immer alle und in der Reihenfolge von AccessKind und CoreAccessKind (unten). Bei jeder Art stehen die Aktionen, die die Person auf mindestens einem Ding dieser Art ausführen darf. Nutzen Sie das, um ein Menü oder eine Schaltfläche „neu“ zu zeigen, bevor Sie ein einziges Ding gelesen haben.

Die Antwort sagt nie „nein“, wo etwas erlaubt ist. Sie kann „ja“ sagen, während jedes Ding, dem die Person begegnet, trotzdem abgelehnt wird, zum Beispiel wenn eine Regel nur für Dinge mit einem Label gilt, das keines trägt. Entscheiden Sie pro Ding mit allowed_actions.

Bei den KI-Funktionen ist das, was die Regeln der Person erlauben. Eine Anfrage dort kann aus einem anderen Grund noch abgelehnt werden; zeigen Sie dann diese Ablehnung.

Was jemand darf, pro Ding¶

Jedes Ding, das OS zurückgibt, trägt allowed_actions: die Aktionen, die die Person auf genau diesem Ding ausführen darf. Zeigen Sie eine Schaltfläche nur, wenn die Aktion darin steht; die Anfrage hinter der Schaltfläche gelingt dann.

Eine Organisation hat noch eine zweite Liste, parent_allowed_actions: was die Person in der Organisation darüber über sie darf. write dort ist aussetzen, fortsetzen und die Labels ersetzen; delete ist löschen. Für die oberste Organisation und für wen die Organisation darüber nicht erreicht, ist diese Liste leer.

Der Dienst einer Organisation hat dieselben zwei Listen: In parent_allowed_actions bedeutet write, dass die Person dort Pläne und Ausnahmen vergeben und entfernen und das Enddatum einer Demo setzen darf.

Pro Art und pro Ding gilt alles innerhalb des Dienstes der Organisation: Was nicht darin ist, steht in keiner der beiden Listen.

Die Namen im Schema¶

Die Arten und Aktionen sind Aufzählungen im OpenAPI-Schema von OS, mit festen Namen, sodass Sie daraus Ihre eigenen Typen erzeugen können: