De toegangs-API¶

Deze pagina is voor wie een eigen toepassing op OS bouwt en wil weten wat de aangemelde persoon mag, zodat de toepassing alleen knoppen en menu's toont die werken. Ze laat zien hoe je een verzoek aan OS doet, hoe je per soort ding leest wat iemand mag, en wat allowed_actions op elk ding betekent. Wat rollen en regels zijn, staat in Rollen en toegang.

Een verzoek aan OS¶

• Adres. Elke route over een organisatie staat onder /api/v1/organisations/{id}, met het id van de organisatie (org_...).
• Aanmelding. Elk verzoek draagt het toegangstoken van de aangemelde persoon: Authorization: Bearer <token>. OS beslist voor die persoon, in die organisatie.
• Lijsten komen per pagina: limit (hoogstens 200, standaard 50) en cursor. Een antwoord heeft items en, als er meer is, next_cursor. Een lijst toont alleen wat de persoon mag zien, dus een pagina kan minder rijen hebben dan limit terwijl next_cursor toch verder gaat.
• Versies. Een ding dat je in zijn geheel vervangt (een groep, een eigen rol, een eigenschap, het regeldocument) draagt version en de kop ETag. Een wijziging noemt die versie in If-Match; is het ding intussen veranderd, dan antwoordt OS 409.
• Fouten zijn 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": "..."}

Een 422 heeft daarnaast errors, een lijst met per veld field, message en type.

Wat iemand mag, per soort¶

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 noemt elke soort van OS en core_kinds elke soort van de AI-functies, altijd allemaal en in de volgorde van AccessKind en CoreAccessKind (hieronder). Bij elke soort staan de acties die de persoon op minstens één ding van die soort mag. Gebruik dit om een menu of een knop "nieuw" te tonen voordat je één ding hebt gelezen.

Het antwoord zegt nooit "nee" waar iets wel mag. Het kan "ja" zeggen terwijl elk ding dat de persoon tegenkomt toch wordt geweigerd, bijvoorbeeld als een regel alleen geldt voor dingen met een label dat niets draagt. Beslis per ding met allowed_actions.

Bij de AI-functies is dit wat de regels van de persoon toestaan. Een verzoek daar kan nog om een andere reden worden geweigerd; toon dan die weigering.

Wat iemand mag, per ding¶

Elk ding dat OS teruggeeft draagt allowed_actions: de acties die de persoon op precies dat ding mag. Toon een knop alleen als de actie erin staat; het verzoek achter de knop slaagt dan.

Een organisatie heeft nog een tweede lijst, parent_allowed_actions: wat de persoon in de organisatie erboven over haar mag. write daar is opschorten, hervatten en de labels vervangen; delete is verwijderen. Voor de bovenste organisatie, en voor wie de organisatie erboven niet bereikt, is die lijst leeg.

De dienst van een organisatie heeft dezelfde twee lijsten: in parent_allowed_actions betekent write dat de persoon er pakketten en uitzonderingen mag geven en weghalen en de einddatum van een demo mag zetten.

Per soort en per ding geldt alles binnen de dienst van de organisatie: wat er niet in zit, staat in geen van beide lijsten.

De namen in het schema¶

De soorten en acties zijn opsommingen in het OpenAPI-schema van OS, met vaste namen, zodat je je eigen types ervan kunt maken: