ScoDoc/DocScoDoc
7
2
Fork 10
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

Merge pull request 'ajout doc (permission, correctifs tableaux, formsemestre-programme, ...)' (#43) from jmplace/DocScoDoc:ajout_doc into master

Browse Source 
Reviewed-on: https://scodoc.org/git/viennet/DocScoDoc/pulls/43
This commit is contained in:
Emmanuel Viennet 2022-08-25 18:52:00 +02:00
commit 1c9e95cbab
2 changed files with 82 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
docs/ScoDoc9API.md
View File

@ -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 ## 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 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. 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 * suivi de `:` puis d'un nom en majuscule indique une requête (POST) qui modifie
les données de ScoDoc. les données de ScoDoc.
| Retour | Remarque | Méthode | Navigation | | Retour | Remarque | Méthode | Navigation | Permission |
|:------------------------|:----------------------------------------|---------|---------------------------------------------------------------------------| |:------------------------|:----------------------------------------|---------|---------------------------------------------------------------------------|---------------------|
| departement**`*`** | tous les depts | GET | [departements](#departements) | | departement**`*`** | tous les depts | GET | [departements](#departements) | |
| departement**`#`** | tous les ids des depts | GET | [departements-ids](#departements-ids) | | departement**`#`** | tous les ids des depts | GET | [departements-ids](#departements-ids) | ScoView |
| departement | recherche par id | GET | [departement](#departement) | | departement | recherche par id | GET | [departement](#departement) | ScoView |
| departement | recherche par acronyme | GET | [departement](#departement) | | departement | recherche par acronyme | GET | [departement](#departement) | ScoView |
| departement:CREATE | création d'un département | POST | [departement-create](#departement-create) | | 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) | | departement:EDIT | modification d'un département | POST | [departement-edit](#departement-edit) | ScoSuperAdmin |
| departementDELETE | suppression d'un département | POST | [departement-delete](#departement-delete) | | departementDELETE | suppression d'un département | POST | [departement-delete](#departement-delete) | ScoSuperAdmin |
| formation**`*`** | toutes les formations accessibles | GET | [formations](#formations) | | formation**`*`** | toutes les formations accessibles | GET | [formations](#formations) | ScoView |
| formation**`#`** | ids des formations accessibles | GET | [formations-ids](#formations-ids) | | formation**`#`** | ids des formations accessibles | GET | [formations-ids](#formations-ids) | ScoView |
| formation | une formation | GET | [formation](#formation) | | formation | une formation | GET | [formation](#formation) | ScoView |
| export | | GET | [formation-export](#formation-export) | | export | | GET | [formation-export](#formation-export) | ScoView |
| export**`+`** | | GET | [formation-export_with_ids](#formation-export_with_ids) | | export**`+`** | | GET | [formation-export_with_ids](#formation-export_with_ids) | ScoView |
| referentiel_competences | | GET | [formation-referenciel_competences](#formation-referenciel_competences) | | referentiel_competences | | GET | [formation-referenciel_competences](#formation-referenciel_competences) | ScoView |
| formsemestre**`#`** | | GET | [departement-formsemestres_ids](#departement-formsemestres_ids) | | formsemestre**`#`** | | GET | [departement-formsemestres_ids](#departement-formsemestres_ids) | ScoView |
| formsemestre**`*`** | | GET | [departement-formsemestres_courants](#departement-formsemestres_courants) | | formsemestre**`*`** | | GET | [departement-formsemestres_courants](#departement-formsemestres_courants) | ScoView |
| formsemestre**`*`** | | GET | [formsemestre-query](#formsemestre-query) | | formsemestre**`*`** | | GET | [formsemestre-query](#formsemestre-query) | ScoView |
| formsemestre**`*`** | | GET | [etudiant-formsemestres](#etudiant-formsemestres) | | formsemestre**`*`** | | GET | [etudiant-formsemestres](#etudiant-formsemestres) | ScoView |
| formsemestre | | GET | [formsemestre](#formsemestre) | | formsemestre | | GET | [formsemestre](#formsemestre) | ScoView |
| moduleimpl | | GET | [moduleimpl](#moduleimpl) | | moduleimpl | | GET | [moduleimpl](#moduleimpl) | ScoView |
| partition**`*`** | | GET | [formsemestre-partitions](#formsemestre-partitions) | | partition**`*`** | | GET | [formsemestre-partitions](#formsemestre-partitions) | ScoView |
| partition | | GET | [partition](#partition) | | partition | | GET | [partition](#partition) | ScoView |
| partition:CREATE | | POST | [formsemestre-partition-create](#formsemestre-partition-create) | | partition:CREATE | | POST | [formsemestre-partition-create](#formsemestre-partition-create) | ScoEtudChangeGroups |
| partition:EDIT | | POST | [partition-edit](#partition-edit) | | partition:EDIT | | POST | [partition-edit](#partition-edit) | ScoEtudChangeGroups |
| partition:ACTION | | POST | [formsemestre-partitions-order](#formsemestre-partitions-order) | | partition:ACTION | | POST | [formsemestre-partitions-order](#formsemestre-partitions-order) | ScoEtudChangeGroups |
| partition:DELETE | | POST | [partition-delete](#partition-delete) | | partition:DELETE | | POST | [partition-delete](#partition-delete) | ScoEtudChangeGroups |
| partition:ACTION | | POST | [partition-remove_etudiant](#partition-remove_etudiant) | | partition:ACTION | | POST | [partition-remove_etudiant](#partition-remove_etudiant) | ScoEtudChangeGroups |
| group:CREATE | | POST | [partition-group-create](#partition-group-create) | | group:CREATE | | POST | [partition-group-create](#partition-group-create) | ScoEtudChangeGroups |
| group:EDIT | | POST | [group-edit](#group-edit) | | group:EDIT | | POST | [group-edit](#group-edit) | ScoEtudChangeGroups |
| group:ACTION | | POST | [partition-groups-order](#partition-groups-order) | | group:ACTION | | POST | [partition-groups-order](#partition-groups-order) | ScoEtudChangeGroups |
| group:DELETE | | POST | [group-delete](#group-delete) | | group:DELETE | | POST | [group-delete](#group-delete) | ScoEtudChangeGroups |
| group* | | POST | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups) | | group* | | GET | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups) | ScoView |
| group:ACTION | | GET | [group-set_etudiant](#group-set_etudiant) | | group:ACTION | | POST | [group-set_etudiant](#group-set_etudiant) | ScoEtudChangeGroups |
| group:ACTION | | POST | [group-remove_etudiant](#group-remove_etudiant) | | group:ACTION | | POST | [group-remove_etudiant](#group-remove_etudiant) | ScoEtudChangeGroups |
| etudiant**`*`** | recherche par etudid, nip ou i | GET | [etudiants-clé](#etudiants-clé) | | etudiant**`*`** | recherche par etudid, nip ou ine | GET | [etudiants-clef](#etudiants-clef) | ScoView |
| etudiant**`*`** | les étudiants actuels | GET | [etudiants-courant](#etudiants-courant) | | etudiant**`*`** | les étudiants actuels | GET | [etudiants-courant](#etudiants-courant) | ScoView |
| etudiant**`*`** | | GET | [departement-etudiants](#departement-etudiants) | | etudiant**`*`** | | GET | [departement-etudiants](#departement-etudiants) | ScoView |
| etudiant**`*`** | | GET | [formsemestre-etudiants](#formsemestre-etudiants) | | etudiant**`*`** | | GET | [formsemestre-etudiants](#formsemestre-etudiants) | ScoView |
| etudiant**`*`** | | GET | [formsemestre-etudiants-query](#formsemestre-etudiants-query) | | etudiant**`*`** | | GET | [formsemestre-etudiants-query](#formsemestre-etudiants-query) | ScoView |
| etudiant**`*`** | | GET | [group-etudiants](#group-etudiants) | | etudiant**`*`** | | GET | [group-etudiants](#group-etudiants) | ScoView |
| etudiant**`*`** | | GET | [group-etudiants-query](#group-etudiants-query) | | etudiant**`*`** | | GET | [group-etudiants-query](#group-etudiants-query) |
| etudiant | | GET | [etudiant](#etudiant) | | etudiant | | GET | [etudiant](#etudiant) | ScoView |
| bulletin**`*`** | | GET | [formsemestre-bulletin](#formsemestre-bulletin) | | bulletin**`*`** | | GET | [formsemestre-bulletin](#formsemestre-bulletin) | ScoView |
| bulletin | | GET | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin) | | bulletin | | GET | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin) | ScoView |
| programme | | GET | [formsemestre-programme](#formsemestre-programme) | | programme | | GET | [formsemestre-programme](#formsemestre-programme) | ScoView |
| | | GET | [formsemestre-etat_evals](#formsemestre-etat_evals) | | | | GET | [formsemestre-etat_evals](#formsemestre-etat_evals) | ScoView |
| | | GET | [formsemestre-resultats](#formsemestre-resultats) | | | | GET | [formsemestre-resultats](#formsemestre-resultats) | ScoView |
| jury | | GET | [formsemestre-decisions_jury](#formsemestre-decisions_jury) | | jury | | GET | [formsemestre-decisions_jury](#formsemestre-decisions_jury) | ScoView |
| evaluation* | | GET | [evaluations](#evaluations) | | note* | | GET | [evaluation-notes](#evaluation-notes) | ScoView |
| note* | | GET | [evaluation-notes](#evaluation-notes) | | logo**`*`** | | GET | [logos](#logos) | ScoSuperAdmin |
| logo**`*`** | | GET | [logos](#logos) | | logo**`*`** | | GET | [departement-logos](#departement-logos) | ScoSuperAdmin |
| logo**`*`** | | GET | [departement-logos](#departement-logos) | | logo | | GET | [logo](#logo) | ScoSuperAdmin |
| logo | | GET | [logo](#logo) | | logo | | GET | [departement-logo](#departement-logo) | ScoSuperAdmin |
| logo | | GET | [departement-logo](#departement-logo) | | user | | GET | [user](#user) | ScoUsView |
| user | | GET | [user](#user) | | user**`*`** | | GET | [users-query](#users-query) | ScoUsView |
| user**`*`** | | GET | [users-query](#users-query) | | user:CREATE | | POST | [user-create](#user-create) | ScoUserAdmin |
| user:CREATE | | POST | [user-create](#user-create) | | user:EDIT | | POST | [user-edit](#user-edit) | ScoUserAdmin |
| user:EDIT | | POST | [user-edit](#user-edit) | | user:PASSWORD | change le mot de passe d'un utilisateur | POST | [user-password](#user-password) | ScoUserAdmin |
| user:PASSWORD | change le mot de passe d'un utilisateur | POST | [user-password](#user-password) | | user:ACTION | | POST | [user-role-add](#user-role-add) | ScoUserAdmin |
| user:DELETE | | POST | [user-delete](#user-delete) | | user:ACTION | | POST | [user-role-remove](#user-role-remove) | ScoUserAdmin |
| user:ACTION | | POST | [user-role-add](#user-role-add) | | permission**`*`** | | GET | [permissions](#permissions) | ScoUsView |
| user:ACTION | | POST | [user-role-remove](#user-role-remove) | | role**`*`** | | GET | [roles](#roles) | ScoUsView |
| permission**`*`** | | GET | [permissions](#permissions) | | role**`*`** | | GET | [role](#role) | ScoUsView |
| role**`*`** | | GET | [roles](#roles) | | role:ACTION | | POST | [role-add_permission](#role-add_permission) | ScoUserAdmin |
| role**`*`** | | GET | [role](#role) | | role:ACTION | | POST | [role-remove_permission](#role-remove_permission) | ScoUserAdmin |
| role:ACTION | | POST | [role-add_permission](#role-add_permission) | | role:CREATE | | POST | [role-create](#role-create) | ScoUserAdmin |
| role:ACTION | | POST | [role-remove_permission](#role-remove_permission) | | role:EDIT | | POST | [role-edit](#role-edit) | ScoUserAdmin |
| role:CREATE | | POST | [role-create](#role-create) | | role:DELETE | | POST | [role-delete](#role-delete) | ScoUserAdmin |
| role:EDIT | | POST | [role-edit](#role-edit) |
| role:DELETE | | POST | [role-delete](#role-delete) |
#### Note sur les exemples d'utilisation #### 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: 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. l'id passé en paramètres.
Les codes INE et NIP sont uniques au sein d'un département. 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. 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) * **Exemple de résultat:** [etudiant.json](samples/sample_etudiant.json.md)
### **API Formation** ### **API Formation**
@ -841,7 +844,7 @@ d'un nombre quelconque de groupes d'étudiants.
#### **`partition-remove_etudiant`** #### **`partition-remove_etudiant`**
* **Méthode: POST** * **Méthode: POST**
* **Permission: `ScoEtudsChangeGroups`** * **Permission: `ScoEtudsChangeGroups`**
* **Permission: `ScoEtudChangeGroups`*** * **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `partition_id` * **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>/remove_etudiant/<int:etudid>` * **Routes:** `/partition/<int:partition_id>/remove_etudiant/<int:etudid>`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/remove_etudiant/12107` * **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` * **Paramètres:** `dept`, `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/programme` * **Routes:** `/formsemestre/<int:formsemestre_id>/programme`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/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) * **Exemple de résultat:** [formsemestre-programme.json](samples/sample_formsemestre-programme.json.md)
#### **formsemestre-resultats** #### **formsemestre-resultats**

1
docs/samples/sample_formsemestre-programme.json.md
View File

@ -3,6 +3,7 @@
#### GET /formsemestre/1/programme #### GET /formsemestre/1/programme
```json ```json
{ {
"malus": [],
"modules": [], "modules": [],
"ressources": [ "ressources": [
{ {