L'API d'accès¶

Cette page s'adresse à qui construit une application propre sur OS et veut savoir ce que la personne connectée peut faire, afin que l'application n'affiche que des boutons et des menus qui fonctionnent. Elle montre comment faire une requête à OS, comment lire par type d'élément ce que quelqu'un peut faire, et ce que signifie allowed_actions sur chaque élément. Ce que sont les rôles et les règles figure dans Rôles et accès.

Une requête à OS¶

• Adresse. Chaque route concernant une organisation se trouve sous /api/v1/organisations/{id}, avec l'identifiant de l'organisation (org_...).
• Connexion. Chaque requête porte le jeton d'accès de la personne connectée : Authorization: Bearer <token>. OS décide pour cette personne, dans cette organisation.
• Les listes viennent par pages : limit (200 au maximum, 50 par défaut) et cursor. Une réponse a items et, s'il y en a davantage, next_cursor. Une liste ne montre que ce que la personne a le droit de voir ; une page peut donc avoir moins de lignes que limit alors que next_cursor continue.
• Versions. Un élément que vous remplacez dans son ensemble (un groupe, un rôle propre, un attribut, le document de règles) porte version et l'en-tête ETag. Une modification indique cette version dans If-Match ; si l'élément a changé entre-temps, OS répond 409.
• Les erreurs sont du 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": "..."}

Un 422 a en plus errors, une liste avec, par champ, field, message et type.

Ce que quelqu'un peut faire, par type¶

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 nomme chaque type d'OS et core_kinds chaque type des fonctions d'IA, toujours tous et dans l'ordre de AccessKind et CoreAccessKind (ci-dessous). Pour chaque type figurent les actions que la personne peut faire sur au moins un élément de ce type. Utilisez cela pour afficher un menu ou un bouton « nouveau » avant d'avoir lu un seul élément.

La réponse ne dit jamais « non » là où quelque chose est permis. Elle peut dire « oui » alors que chaque élément que la personne rencontre est tout de même refusé, par exemple si une règle ne vaut que pour les éléments portant une étiquette que rien ne porte. Décidez par élément avec allowed_actions.

Pour les fonctions d'IA, c'est ce que les règles de la personne permettent. Une requête y peut encore être refusée pour une autre raison ; affichez alors ce refus.

Ce que quelqu'un peut faire, par élément¶

Chaque élément qu'OS renvoie porte allowed_actions : les actions que la personne peut faire sur précisément cet élément. N'affichez un bouton que si l'action y figure ; la requête derrière le bouton réussit alors.

Une organisation a une seconde liste, parent_allowed_actions : ce que la personne peut faire à son sujet dans l'organisation au-dessus. write y signifie suspendre, rétablir et remplacer les étiquettes ; delete signifie supprimer. Pour l'organisation du sommet, et pour qui n'atteint pas l'organisation au-dessus, cette liste est vide.

Le service d'une organisation a les deux mêmes listes : dans parent_allowed_actions, write signifie que la personne peut y donner et retirer des offres et des exceptions et fixer la date de fin d'une démo.

Par type et par élément, tout vaut dans le service de l'organisation : ce qui n'en fait pas partie ne figure dans aucune des deux listes.

Les noms dans le schéma¶

Les types et les actions sont des énumérations du schéma OpenAPI d'OS, avec des noms fixes, pour que vous puissiez en faire vos propres types :