From 113a9c9219c1de3f46de6eb1e0d4307fc705eb95 Mon Sep 17 00:00:00 2001 From: Jean-Marie PLACE Date: Thu, 25 Aug 2022 18:39:17 +0200 Subject: [PATCH] ajout doc (permission, correctifs tableaux, formsemestre-programme, ...) --- docs/ScoDoc9API.md | 154 +++++++++--------- .../sample_formsemestre-programme.json.md | 1 + 2 files changed, 82 insertions(+), 73 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index e55590ff..ae41f004 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -27,7 +27,11 @@ L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction ## Configuration de ScoDoc pour utiliser l'API -Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats. +Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats. + +Les droits à accorder dépendent des fonctionnalités nécessaires. la permission `ScoView` est généralement suffisante car elle permet toutes les consultations. +Cependant si, par l'API, on veut effectuer des opérations de modification ou encore consulter les comptes utilisateurs, d'autres droits (`ScoChangeGroups`, `ScoUsersView`, `ScoSuperAdmin`, ...) peuvent être requis. +La consultation du [tableau récapitulatif](#tableau-recapitulatif-des-entrees-de-lapi) ou la ligne `permission`de chaque entrée vous donnera la permission requise pour chaque opération. En général, il est recommandé de créer un rôle, de lui attribuer les permissions que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle. @@ -204,77 +208,75 @@ Ce tableau est trié selon le type des informations renvoyées: * suivi de `:` puis d'un nom en majuscule indique une requête (POST) qui modifie les données de ScoDoc. -| Retour | Remarque | Méthode | Navigation | -|:------------------------|:----------------------------------------|---------|---------------------------------------------------------------------------| -| departement**`*`** | tous les depts | GET | [departements](#departements) | -| departement**`#`** | tous les ids des depts | GET | [departements-ids](#departements-ids) | -| departement | recherche par id | GET | [departement](#departement) | -| departement | recherche par acronyme | GET | [departement](#departement) | -| departement:CREATE | création d'un département | POST | [departement-create](#departement-create) | -| departement:EDIT | modification d'un département | POST | [departement-edit](#departement-edit) | -| departementDELETE | suppression d'un département | POST | [departement-delete](#departement-delete) | -| formation**`*`** | toutes les formations accessibles | GET | [formations](#formations) | -| formation**`#`** | ids des formations accessibles | GET | [formations-ids](#formations-ids) | -| formation | une formation | GET | [formation](#formation) | -| export | | GET | [formation-export](#formation-export) | -| export**`+`** | | GET | [formation-export_with_ids](#formation-export_with_ids) | -| referentiel_competences | | GET | [formation-referenciel_competences](#formation-referenciel_competences) | -| formsemestre**`#`** | | GET | [departement-formsemestres_ids](#departement-formsemestres_ids) | -| formsemestre**`*`** | | GET | [departement-formsemestres_courants](#departement-formsemestres_courants) | -| formsemestre**`*`** | | GET | [formsemestre-query](#formsemestre-query) | -| formsemestre**`*`** | | GET | [etudiant-formsemestres](#etudiant-formsemestres) | -| formsemestre | | GET | [formsemestre](#formsemestre) | -| moduleimpl | | GET | [moduleimpl](#moduleimpl) | -| partition**`*`** | | GET | [formsemestre-partitions](#formsemestre-partitions) | -| partition | | GET | [partition](#partition) | -| partition:CREATE | | POST | [formsemestre-partition-create](#formsemestre-partition-create) | -| partition:EDIT | | POST | [partition-edit](#partition-edit) | -| partition:ACTION | | POST | [formsemestre-partitions-order](#formsemestre-partitions-order) | -| partition:DELETE | | POST | [partition-delete](#partition-delete) | -| partition:ACTION | | POST | [partition-remove_etudiant](#partition-remove_etudiant) | -| group:CREATE | | POST | [partition-group-create](#partition-group-create) | -| group:EDIT | | POST | [group-edit](#group-edit) | -| group:ACTION | | POST | [partition-groups-order](#partition-groups-order) | -| group:DELETE | | POST | [group-delete](#group-delete) | -| group* | | POST | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups) | -| group:ACTION | | GET | [group-set_etudiant](#group-set_etudiant) | -| group:ACTION | | POST | [group-remove_etudiant](#group-remove_etudiant) | -| etudiant**`*`** | recherche par etudid, nip ou i | GET | [etudiants-clé](#etudiants-clé) | -| etudiant**`*`** | les étudiants actuels | GET | [etudiants-courant](#etudiants-courant) | -| etudiant**`*`** | | GET | [departement-etudiants](#departement-etudiants) | -| etudiant**`*`** | | GET | [formsemestre-etudiants](#formsemestre-etudiants) | -| etudiant**`*`** | | GET | [formsemestre-etudiants-query](#formsemestre-etudiants-query) | -| etudiant**`*`** | | GET | [group-etudiants](#group-etudiants) | +| Retour | Remarque | Méthode | Navigation | Permission | +|:------------------------|:----------------------------------------|---------|---------------------------------------------------------------------------|---------------------| +| departement**`*`** | tous les depts | GET | [departements](#departements) | | +| departement**`#`** | tous les ids des depts | GET | [departements-ids](#departements-ids) | ScoView | +| departement | recherche par id | GET | [departement](#departement) | ScoView | +| departement | recherche par acronyme | GET | [departement](#departement) | ScoView | +| departement:CREATE | création d'un département | POST | [departement-create](#departement-create) | ScoSuperAdmin | +| departement:EDIT | modification d'un département | POST | [departement-edit](#departement-edit) | ScoSuperAdmin | +| departementDELETE | suppression d'un département | POST | [departement-delete](#departement-delete) | ScoSuperAdmin | +| formation**`*`** | toutes les formations accessibles | GET | [formations](#formations) | ScoView | +| formation**`#`** | ids des formations accessibles | GET | [formations-ids](#formations-ids) | ScoView | +| formation | une formation | GET | [formation](#formation) | ScoView | +| export | | GET | [formation-export](#formation-export) | ScoView | +| export**`+`** | | GET | [formation-export_with_ids](#formation-export_with_ids) | ScoView | +| referentiel_competences | | GET | [formation-referenciel_competences](#formation-referenciel_competences) | ScoView | +| formsemestre**`#`** | | GET | [departement-formsemestres_ids](#departement-formsemestres_ids) | ScoView | +| formsemestre**`*`** | | GET | [departement-formsemestres_courants](#departement-formsemestres_courants) | ScoView | +| formsemestre**`*`** | | GET | [formsemestre-query](#formsemestre-query) | ScoView | +| formsemestre**`*`** | | GET | [etudiant-formsemestres](#etudiant-formsemestres) | ScoView | +| formsemestre | | GET | [formsemestre](#formsemestre) | ScoView | +| moduleimpl | | GET | [moduleimpl](#moduleimpl) | ScoView | +| partition**`*`** | | GET | [formsemestre-partitions](#formsemestre-partitions) | ScoView | +| partition | | GET | [partition](#partition) | ScoView | +| partition:CREATE | | POST | [formsemestre-partition-create](#formsemestre-partition-create) | ScoEtudChangeGroups | +| partition:EDIT | | POST | [partition-edit](#partition-edit) | ScoEtudChangeGroups | +| partition:ACTION | | POST | [formsemestre-partitions-order](#formsemestre-partitions-order) | ScoEtudChangeGroups | +| partition:DELETE | | POST | [partition-delete](#partition-delete) | ScoEtudChangeGroups | +| partition:ACTION | | POST | [partition-remove_etudiant](#partition-remove_etudiant) | ScoEtudChangeGroups | +| group:CREATE | | POST | [partition-group-create](#partition-group-create) | ScoEtudChangeGroups | +| group:EDIT | | POST | [group-edit](#group-edit) | ScoEtudChangeGroups | +| group:ACTION | | POST | [partition-groups-order](#partition-groups-order) | ScoEtudChangeGroups | +| group:DELETE | | POST | [group-delete](#group-delete) | ScoEtudChangeGroups | +| group* | | GET | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups) | ScoView | +| group:ACTION | | POST | [group-set_etudiant](#group-set_etudiant) | ScoEtudChangeGroups | +| group:ACTION | | POST | [group-remove_etudiant](#group-remove_etudiant) | ScoEtudChangeGroups | +| etudiant**`*`** | recherche par etudid, nip ou ine | GET | [etudiants-clef](#etudiants-clef) | ScoView | +| etudiant**`*`** | les étudiants actuels | GET | [etudiants-courant](#etudiants-courant) | ScoView | +| etudiant**`*`** | | GET | [departement-etudiants](#departement-etudiants) | ScoView | +| etudiant**`*`** | | GET | [formsemestre-etudiants](#formsemestre-etudiants) | ScoView | +| etudiant**`*`** | | GET | [formsemestre-etudiants-query](#formsemestre-etudiants-query) | ScoView | +| etudiant**`*`** | | GET | [group-etudiants](#group-etudiants) | ScoView | | etudiant**`*`** | | GET | [group-etudiants-query](#group-etudiants-query) | -| etudiant | | GET | [etudiant](#etudiant) | -| bulletin**`*`** | | GET | [formsemestre-bulletin](#formsemestre-bulletin) | -| bulletin | | GET | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin) | -| programme | | GET | [formsemestre-programme](#formsemestre-programme) | -| | | GET | [formsemestre-etat_evals](#formsemestre-etat_evals) | -| | | GET | [formsemestre-resultats](#formsemestre-resultats) | -| jury | | GET | [formsemestre-decisions_jury](#formsemestre-decisions_jury) | -| evaluation* | | GET | [evaluations](#evaluations) | -| note* | | GET | [evaluation-notes](#evaluation-notes) | -| logo**`*`** | | GET | [logos](#logos) | -| logo**`*`** | | GET | [departement-logos](#departement-logos) | -| logo | | GET | [logo](#logo) | -| logo | | GET | [departement-logo](#departement-logo) | -| user | | GET | [user](#user) | -| user**`*`** | | GET | [users-query](#users-query) | -| user:CREATE | | POST | [user-create](#user-create) | -| user:EDIT | | POST | [user-edit](#user-edit) | -| user:PASSWORD | change le mot de passe d'un utilisateur | POST | [user-password](#user-password) | -| user:DELETE | | POST | [user-delete](#user-delete) | -| user:ACTION | | POST | [user-role-add](#user-role-add) | -| user:ACTION | | POST | [user-role-remove](#user-role-remove) | -| permission**`*`** | | GET | [permissions](#permissions) | -| role**`*`** | | GET | [roles](#roles) | -| role**`*`** | | GET | [role](#role) | -| role:ACTION | | POST | [role-add_permission](#role-add_permission) | -| role:ACTION | | POST | [role-remove_permission](#role-remove_permission) | -| role:CREATE | | POST | [role-create](#role-create) | -| role:EDIT | | POST | [role-edit](#role-edit) | -| role:DELETE | | POST | [role-delete](#role-delete) | +| etudiant | | GET | [etudiant](#etudiant) | ScoView | +| bulletin**`*`** | | GET | [formsemestre-bulletin](#formsemestre-bulletin) | ScoView | +| bulletin | | GET | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin) | ScoView | +| programme | | GET | [formsemestre-programme](#formsemestre-programme) | ScoView | +| | | GET | [formsemestre-etat_evals](#formsemestre-etat_evals) | ScoView | +| | | GET | [formsemestre-resultats](#formsemestre-resultats) | ScoView | +| jury | | GET | [formsemestre-decisions_jury](#formsemestre-decisions_jury) | ScoView | +| note* | | GET | [evaluation-notes](#evaluation-notes) | ScoView | +| logo**`*`** | | GET | [logos](#logos) | ScoSuperAdmin | +| logo**`*`** | | GET | [departement-logos](#departement-logos) | ScoSuperAdmin | +| logo | | GET | [logo](#logo) | ScoSuperAdmin | +| logo | | GET | [departement-logo](#departement-logo) | ScoSuperAdmin | +| user | | GET | [user](#user) | ScoUsView | +| user**`*`** | | GET | [users-query](#users-query) | ScoUsView | +| user:CREATE | | POST | [user-create](#user-create) | ScoUserAdmin | +| user:EDIT | | POST | [user-edit](#user-edit) | ScoUserAdmin | +| user:PASSWORD | change le mot de passe d'un utilisateur | POST | [user-password](#user-password) | ScoUserAdmin | +| user:ACTION | | POST | [user-role-add](#user-role-add) | ScoUserAdmin | +| user:ACTION | | POST | [user-role-remove](#user-role-remove) | ScoUserAdmin | +| permission**`*`** | | GET | [permissions](#permissions) | ScoUsView | +| role**`*`** | | GET | [roles](#roles) | ScoUsView | +| role**`*`** | | GET | [role](#role) | ScoUsView | +| role:ACTION | | POST | [role-add_permission](#role-add_permission) | ScoUserAdmin | +| role:ACTION | | POST | [role-remove_permission](#role-remove_permission) | ScoUserAdmin | +| role:CREATE | | POST | [role-create](#role-create) | ScoUserAdmin | +| role:EDIT | | POST | [role-edit](#role-edit) | ScoUserAdmin | +| role:DELETE | | POST | [role-delete](#role-delete) | ScoUserAdmin | #### Note sur les exemples d'utilisation Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-traitements non réalisés par l'API. Il n'est par exemple pas garanti que les clés des objets json sont triées: @@ -483,6 +485,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post- l'id passé en paramètres. Les codes INE et NIP sont uniques au sein d'un département. Si plusieurs objets étudiant ont le même code, on renvoie le plus récemment inscrit. +* Pour obtenir tous les étudiants répondant au critère, utiliser [etudiant-clefs](#etudiants-clef) * **Exemple de résultat:** [etudiant.json](samples/sample_etudiant.json.md) ### **API Formation** @@ -841,7 +844,7 @@ d'un nombre quelconque de groupes d'étudiants. #### **`partition-remove_etudiant`** * **Méthode: POST** * **Permission: `ScoEtudsChangeGroups`** -* **Permission: `ScoEtudChangeGroups`*** +* **Permission: `ScoEtudChangeGroups`** * **Paramètres:** `partition_id` * **Routes:** `/partition//remove_etudiant/` * **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/remove_etudiant/12107` @@ -1054,7 +1057,12 @@ mais pas JSON compliant à cause des _NaN_. * **Paramètres:** `dept`, `formsemestre_id` * **Routes:** `/formsemestre//programme` * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/programme` -* **Résultat:** Retourne la liste des UEs, modules, ressources et SAE d'un semestre. +* **Résultat:** Retourne la struture d'un formsemestre sous 5 entrées d'un dictionnaire: + * **`ues`**: liste des UEs, + * **`ressources`**: liste des ressources (BUT), + * **`saes`**: liste des saes (BUT), + * **`modules`**: liste des modules classiques (DUT ou sport/culture) + * **`malus`**: listes des modules de type bonus/malus. * **Exemple de résultat:** [formsemestre-programme.json](samples/sample_formsemestre-programme.json.md) #### **formsemestre-resultats** diff --git a/docs/samples/sample_formsemestre-programme.json.md b/docs/samples/sample_formsemestre-programme.json.md index 9805395e..dbb3004d 100644 --- a/docs/samples/sample_formsemestre-programme.json.md +++ b/docs/samples/sample_formsemestre-programme.json.md @@ -3,6 +3,7 @@ #### GET /formsemestre/1/programme ```json { + "malus": [], "modules": [], "ressources": [ {