From 67cf0163edf328b8577373fee9bf934db91b019f Mon Sep 17 00:00:00 2001 From: viennet Date: Thu, 11 Aug 2022 15:41:20 +0200 Subject: [PATCH] API: user, roles, ... --- docs/ScoDoc9API.md | 162 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 140 insertions(+), 22 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index e39610432..fdcd7a713 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -293,13 +293,43 @@ Ce tableau est trié selon le type des informations renvoyées: * **Exemple de résultat:** [departement.json](samples/sample_departement.json.md) #### **`departement-create`** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Paramètres:** aucun +* **Data:** `{ "acronym": str, "visible":bool }` +* **Routes:** `/departement/create` +* **Exemple d'utilisation:** `/departement/create` +>`{ "acronym": "QLIO", "visible": true }` +* **Résultat:** Crée un nouveau département. L'acronyme du département (RT, + GEII, ...) doit être unique (il est d'usage de le mettre en majuscules, mais + ce n'est pas obligatoire). Le paramètre optionnel `visible`indique si le + département est affiché sur la page d'accueil de ScoDoc. Notez qu'un + département "invisible" peut quand même être utilisé si l'on connait son + adresse (URL). Renvoie le département créé. + #### **`departement-edit`** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Paramètres:** `dept_acronym` +* **Data:** `{ "visible":bool }` +* **Routes:** `/departement//edit` +* **Exemple d'utilisation:** `/departement/edit` +>`{ "visible": false }` +* **Résultat:** Modifie un département. Seul le champs `visible` peut être + modifié. L'acronyme ne peut pas être changé car il peut être mentionné dans de + nombreux objets et documents, y compris à l'extérieur de ScoDoc. + + #### **`departement-delete`** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Paramètres:** `dept_acronym` +* **Routes:** `/departement//delete` +* **Exemple d'utilisation:** `/departement/delete/EARTH` +* **Résultat:** supprime définitivement un département. *Toutes les données sont effacées* + (étudiants, formations, ...). ### **API Etudiant** #### Structure Etudiant @@ -786,26 +816,65 @@ d'un nombre quelconque de groupes d'étudiants. ### **API Role** +Les rôles ont un nom et sont associés à un ensemble de permissions. Un +utilisateur pourra être associé à un ou plusieurs rôles dans chaque département +(ainsi, il ou elle peut enseigner dans un département et être administrateur +d'un autre). + #### **roles** -TODO +* **Méthode:** GET +* **Routes:** `/roles` +* **Exemple d'utilisation:** `/roles` +* **Résultat:** Liste de tous les rôles. +* **Exemple de résultat:** [roles.json](samples/sample_roles.json.md) #### **role** -TODO +* **Méthode:** GET +* **Routes:** `/role/` +* **Exemple d'utilisation:** `/role/Ens` +* **Résultat:** Liste le rôle indiqué. 404 si inexistant. +* **Exemple de résultat:** [role.json](samples/sample_role.json.md) #### **role-add_permission** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Routes:** `/role//add_permission/` +* **Exemple d'utilisation:** `/role/Ens/add_permission/ScoView` +* **Résultat:** Ajoute la permission au rôle. 404 si l'un des deux n'existe pas. + Note: la liste des permissions est donnée sur [ConfigPermissions](ConfigPermissions.md). #### **role-remove_permission** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Routes:** `/role//remove_permission/` +* **Exemple d'utilisation:** `/role/Ens/remove_permission/ScoView` +* **Résultat:** Retire la permission au rôle. 404 si l'un des deux n'existe pas. + Si le rôle n'a pas la permission, ne fait rien. #### **role-create** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Data:** `{ "permissions" : [ permission, ... ] }` +* **Routes:** `/role/create/` +* **Exemple d'utilisation:** `/role/create/LaveurDecarreaux` +> `{ "permissions" : [ 'ScoView', 'ScoUsersView' ] }` +* **Résultat:** Crée un nouveau rôle, avec les permissions indiquées. #### **role-delete** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Routes:** `/role//delete` +* **Exemple d'utilisation:** `/role/LaveurDeCarreaux/delete` +* **Résultat:** Supprime ce rôle. #### **role-edit** -TODO +* **Méthode: POST** +* **Permission: `ScoSuperAdmin`** +* **Data:** `{ "permissions" : [ permission, ... ] }` +* **Routes:** `/role/edit/` +* **Exemple d'utilisation:** `/role/create/LaveurDecarreaux` +> `{ "name" : "LaveurDeVitres", "permissions" : [ 'ScoView' ] }` +* **Résultat:** Modifie le rôle: son nom et/ou ses permissions. ### **API User, Permissions** #### **user** @@ -817,22 +886,68 @@ TODO * **Exemple de résultat:** [user.json](samples/sample_user.json.md) #### **`user-create`** -TODO +* **Méthode: POST** +* **Permission: `ScoUsersAdmin`** +* **Data:** +``` +{ + "user_name": str, + "dept": str or null, + "nom": str, + "prenom": str, + "active":bool (default True) +} +``` +* **Routes:** `/user/create` +* **Résultat:** Crée un nouvel utilisateur. `user_name`est le login, unique et + non modifiable. L'utilisateur est normalement rattaché à un département, sauf + si est "super-administrateur". + +#### **`users-query`** +* **Méthode:** GET +* **Routes:** + * `/users/query?departement=dept_acronym&active=1&starts_with=` +* **Résultat:** Liste d'utilisateurs, filtrés par département, statut, début de + nom (paramètres tous optionnels). Seuls les utilisateurs que l'on a la + permission de voir sont listés. +* **Exemple de résultat:** [users.json](samples/sample_users.json.md) -#### **`user-query`** -TODO #### **`user-edit`** -TODO +* **Méthode: POST** +* **Permission: `ScoUsersAdmin`** +* **Data:** +``` +{ + "dept": str or null, + "nom": str, + "prenom": str, + "active":bool (default True) +} +``` +* **Routes:** `/user//edit` +* **Résultat:** Modifie l'utilisateur d'UID indiqué. #### **`user-role-add`** -TODO +* **Méthode: POST** +* **Permission: `ScoUsersAdmin`** +* **Routes:** `/user//role//add[/departement/]` +* **Résultat:** Attribue le rôle à l'utilisateur, dans le département indiqué + (ou tous si le département n'est pas spécifié).) #### **`user-role-remove`** -TODO +* **Méthode: POST** +* **Permission: `ScoUsersAdmin`** +* **Routes:** `/user//role//remove[/departement/]` +* **Résultat:** Retire le rôle à l'utilisateur. #### **`permissions`** -TODO +* **Méthode:** GET +* **Routes:** `/permissions` +* **Résultat:** Liste des noms des permissions. Ces permissions ne sont pas + modifiables, mais de nouvelles peuvent apparaitre lors des mises à jour du + logiciel. Voir [ConfigPermissions](ConfigPermissions.md). +* **Exemple de résultat:** [permissions.json](samples/sample_permissions.json.md) ### ** API Bulletin, Evaluations, Notes** #### **formsemestre-bulletins** @@ -900,15 +1015,18 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_. * **Exemple d'utilisation:** `/ScoDoc/api/moduleimpl/1/evaluations` * **Résultat:** Retourne la liste des évaluations à partir de l'id d'un moduleimpl (quel que soit leur statut). -* **[Exemple de résultat](samples/sample_moduleimpl-evaluations.json.md)** +* **Exemple de résultat:** [moduleimpl-evaluations.json](samples/sample_moduleimpl-evaluations.json.md) #### **`evaluations-notes`** * **Méthode**: GET * **Paramètres**: `evaluation_id` -* **Routes:** `/evaluations/eval_notes/` -* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/notes/1` -* **Résultat:** Retourne la liste des notes d'une évaluation -* **Exemple de résultat:** TODO XXX +* **Routes:** `/evaluation//notes` +* **Exemple d'utilisation:** `/evaluation/1491/notes` +* **Résultat:** Retourne la liste des notes d'une évaluation. Les valeurs sont + non normalisées (le champ `note_max` indique le barème), et peuvent contenir + des chaînes de caractères: ABS, EXC, DEM, ... +* **Exemple de résultat:** [evaluation-notes.json](samples/sample_evaluation-notes.json.md) + #### **formsemestre-etat_evals** * **Méthode:** GET