API: user, roles, ...

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/<string:dept_acronym>/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/<string:dept_acronym>/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/<str:role_name>`
+* **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/<str:role_name>/add_permission/<str:perm_name>`
+* **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/<str:role_name>/remove_permission/<str:perm_name>`
+* **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/<str:role_name>`
+* **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/<str:role_name>/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/<str:role_name>`
+* **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=<str:nom>`
+* **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/<int:uid>/edit`
+* **Résultat:** Modifie l'utilisateur d'UID indiqué. 
 
 #### **`user-role-add`**
-TODO
+* **Méthode: POST**
+* **Permission: `ScoUsersAdmin`**
+* **Routes:** `/user/<int:uid>/role/<str:role_name>/add[/departement/<string:dept_acronym>]`
+* **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/<int:uid>/role/<str:role_name>/remove[/departement/<string:dept_acronym>]`
+* **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/<int:evaluation_id>`
+* **Routes:** `/evaluation/<int:evaluation_id>/notes`
-* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/notes/1`
+* **Exemple d'utilisation:** `/evaluation/1491/notes`
-* **Résultat:** Retourne la liste des notes d'une évaluation
+* **Résultat:** Retourne la liste des notes d'une évaluation. Les valeurs sont
-* **Exemple de résultat:** TODO XXX
+  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