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

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

View File

@ -29,6 +29,10 @@ L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction
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/<int:partition_id>/remove_etudiant/<int:etudid>`
* **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/<int:formsemestre_id>/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**

View File

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