jmplace/DocScoDoc
1
0
Fork 0
forked from ScoDoc/DocScoDoc
Code Issues Pull Requests Projects Releases Wiki Activity

Formattage doc API

Browse Source
This commit is contained in:
Emmanuel Viennet 2022-10-29 09:16:14 +02:00
parent d2becdc962
commit 4f76da6a29
3 changed files with 194 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@ -5,6 +5,7 @@ Documentation (Web) de ScoDoc, en [MkDocs](https://www.mkdocs.org/).
Version en ligne sur [scodoc.org](https://scodoc.org).
## Historique
L'ancienne documentation de ScoDoc7, hébergée au LIPN sur une plate-forme
[Trac](https://trac.edgewall.org/), a été traduite en
[Markdown](https://www.markdownguide.org/basic-syntax/) en septembre
@ -12,6 +13,26 @@ L'ancienne documentation de ScoDoc7, hébergée au LIPN sur une plate-forme
Le site est depuis hébergé sur [https://scodoc.org].
## Installation mkdocs
Il est recommandé de créer un virtualenv:
```bash
python3.11 -m venv venv
source venv/bin/activate
```
puis d'y installer les composants suivants:
```bash
pip install mkdocs
pip install pymdown-extensions
pip install mkdocs-material
pip install mkdocs-plugin-inline-svg
```
Pour générer le site:
```bash
mkdocs build
```

232
docs/ScoDoc9API.md
View File

@ -174,21 +174,21 @@ par le serveur ScoDoc.
* [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur
inconnue côté serveur.
## Règles générales
## Règles générales
* une route s'écrit comme une suite de noms et d'identifiants;
* les noms token, departement, formation, formsemestre, groupe, etudiant,
bulletin, absence, logo, programme, évaluation, resultat, decision désignent
des types d'objets;
des types d'objets;
* les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query,
create, delete, edit, order sont des actions;
create, delete, edit, order sont des actions;
* les noms restants (ids, courants, long, ...) sont des options, les autres noms
sont des options ou des actions;
sont des options ou des actions;
* le dernier nom apparaissant sur une route donne le type d'objet renvoyé. Ce
nom peut apparaître au singulier ou au pluriel.
* au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404;
* au pluriel une collection d'objets est renvoyée, si aucun objet n'est
trouvé, retourne une collection vide.
* au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404;
* au pluriel une collection d'objets est renvoyée, si aucun objet n'est
trouvé, retourne une collection vide.
* un type d'objet au singulier est généralement suivi immédiatement de son
identifiant (unique). Exception: pour un étudiant, on peut également utiliser
le NIP ou l'INE (qui ne sont pas uniques dans la base car un étudiant de même
@ -287,7 +287,7 @@ Ce tableau est trié selon le type des informations renvoyées:
| role:EDIT | | POST | [role-edit](#role-edit) | ScoUserAdmin |
| role:DELETE | | POST | [role-delete](#role-delete) | ScoUserAdmin |
#### 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:
@ -309,13 +309,15 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
| _date_creation_ | string | date ISO |
#### **departements**
* **Méthode:** GET
* **Routes:** `/departements`
* **Exemple d'utilisation:** `/api/departements`
* **Résultat:** Liste de tous les départements (visibles ou non).
* **Exemple de résultat:** [departements.json](samples/sample_departements.json.md)
#### **departements-ids**
#### **departements-ids**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Routes:** `/departements_ids`
@ -323,23 +325,27 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:**
* **Exemple de résultat:** [departements-ids.json](samples/sample_departements-ids.json.md)
#### **departement**
#### **departement**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Routes:**
* `/departement/id/<int:dept_id>`
* `/departement/<string:dept>`
* `/departement/id/<int:dept_id>`
* `/departement/<string:dept>`
* **Résultat:** Un département
* **Exemple de résultat:** [departement.json](samples/sample_departement.json.md)
#### **`departement-create`**
* **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
@ -349,19 +355,23 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [departements-create.json](samples/sample_departement-create.json.md)
#### **`departement-edit`**
* **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.
* **Exemple de résultat:** [departements-edit.json](samples/sample_departement-edit.json.md)
#### **`departement-delete`**
* **Méthode: POST**
* **Permission: `ScoSuperAdmin`**
* **Paramètres:** `dept_acronym`
@ -372,6 +382,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [departements-delete.json](samples/sample_departement-delete.json.md)
### **API Etudiant**
#### Structure Etudiant
| attribut | type | commentaire |
@ -401,6 +412,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
| _statut_ | string | 'I', 'D' ou 'X' |
#### **`etudiants`** (supprimé)
* **Méthode:** GET
* **Routes:** `/etudiants
* **Exemple d'utilisation:** `/api/etudiants`
@ -409,6 +421,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [etudiants.json] (samples/sample_etudiants.json.md)
#### **`etudiants-courants`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Routes:**
@ -421,6 +434,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [etudiants-courants.json](samples/sample_etudiants-courants.json.md)
#### **`etudiants-clef`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `etudid`, `nip`, `ine`
@ -435,6 +449,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [etudiants-clef.json](samples/sample_etudiants-clef.json.md)
#### **departement-etudiants**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `dept`, `dept_id`
@ -448,6 +463,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [departement-etudiants.json](samples/sample_departement-etudiants.json.md)
#### **`formsemestre-etudiants[-long][-query]`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`
@ -458,35 +474,37 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* `/formsemestre/<int:formsemestre_id>/etudiants/long`
* `/formsemestre/<int:formsemestre_id>/etudiants/long/query?etat=I,D,DEF`
* **Exemple d'utilisation:**
* `/api/formsemestre/1/etudiants/long`
* `/api/formsemestre/1/etudiants/query?etat=D`
* `/api/formsemestre/1/etudiants/long`
* `/api/formsemestre/1/etudiants/query?etat=D`
* **Résultat:** Etudiants d'un formsemestre spécifié par son id.
Une clé (`sort_key`) reproduit [ nom, prenom ] sous forme ASCII, permettant le tri des étudiants.
Avec `query`, La liste est restreinte aux étudiants inscrits (`I`), démissionnaires (`D`) ou défaillants (`DEF`) si l'état est indiqué.
Avec `long`, ajoute la date de naissance entre autre
* **Exemple de résultat:**
* [formsemestre-etudiants.json](samples/sample_formsemestre-etudiants.json.md)
* [formsemestre-etudiants-query.json](samples/sample_formsemestre-etudiants-query.json.md)
* [formsemestre-etudiants.json](samples/sample_formsemestre-etudiants.json.md)
* [formsemestre-etudiants-query.json](samples/sample_formsemestre-etudiants-query.json.md)
#### **`group-etudiants[-query]`**
* **Méthode: GET**
* **Permission: `ScoView`**
* **Paramètres:** `group_id`
* **Query string:** `etat` ('I', 'D' ou 'DEF')
* **Routes:**
* `/group/<int:group_id>/etudiants`
* `/group/<int:group_id>/etudiants/query`
* `/group/<int:group_id>/etudiants`
* `/group/<int:group_id>/etudiants/query`
* **Exemple d'utilisation:**
* `/ScoDoc/api/group/1/etudiants`
* `/ScoDoc/api/group/1/etudiants/query?etat=I`
* **Résultat:** Etudiants d'un groupe spécifié par son id. Liste
* `/ScoDoc/api/group/1/etudiants`
* `/ScoDoc/api/group/1/etudiants/query?etat=I`
* **Résultat:** Etudiants d'un groupe spécifié par son id. Liste
restreinte aux étudiants inscrits (I), démissionnaires (D) ou défaillants
(DEF) si l'état est indiqué.
* **Exemple de résultat:**
* [group-etudiants.json](samples/sample_group-etudiants.json.md)
* [group-etudiants-query.json](samples/sample_group-etudiants-query.json.md)
* [group-etudiants.json](samples/sample_group-etudiants.json.md)
* [group-etudiants-query.json](samples/sample_group-etudiants-query.json.md)
#### **`etudiant`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `etudid`, `nip`, `ine`
@ -530,6 +548,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [formations.json](samples/sample_formations.json.md)
#### **`formations_ids`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Routes:** `/formations_ids`
@ -539,6 +558,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **Exemple de résultat:** [formations_ids.json](samples/sample_formations_ids.json.md)
#### **`formation`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formation_id`
@ -552,6 +572,7 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
Les sessions de formation (qu'elles durent une année ou un mois) sont représentées par les `formsemestre`.
#### Note sur les identifiants de formsemestre
Le `session_id` peut être utilisé pour identifier de façon prévisible et
(presque) unique un formsemestre dans un établissement, ce qui est utile
notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion
@ -568,7 +589,6 @@ des informations suivantes:
une session appartenant à l'année scolaire 2014-2015, même si elle
commence en mars 2015).
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT
informatique de 2014 en formation initiale (FI).
@ -610,18 +630,20 @@ informatique de 2014 en formation initiale (FI).
| _**responsables**_ | int* | liste des ids des enseignants responsables |
#### **departement-formsemestres_ids**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `dept`
* **Routes:**
* `/departement/id/<int:dept_id>/formsemestres_ids`
* `/departement/<string:dept>/formsemestres_ids`
* `/departement/id/<int:dept_id>/formsemestres_ids`
* `/departement/<string:dept>/formsemestres_ids`
* **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_ids`
* **Résultat:** Liste des id des formsemestres (passés ou présents) d'un
département donné.
* **Exemple de résultat:** [departement-formsemestres_ids.json](samples/sample_departement-formsemestres_ids.json.md)
#### **departement-formsemestres-courants**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `dept_id`
@ -633,13 +655,14 @@ informatique de 2014 en formation initiale (FI).
* **Exemple de résultat:** [departement-formsemestres-courants.json](samples/sample_departement-formsemestres-courants.json.md)
#### **formsemestres-query**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** aucun
* **Query string:** `annee_scolaire`, `dept_acronym`, `dept_id`, `etape_apo`, `ine`, `nip`
* **Route:** `/formsemestres/query
* **Exemple d'utilisation:** `/api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021`
* **Résultat:** Description de formsemestres. Si plusieurs
* **Résultat:** Description de formsemestresg. Si plusieurs
paramètres sont donnés, c'est la conjonction (ET) des critères qui est
recherchée. Si aucun formsemestre ne satisfait la requête, une liste vide est
retournée. Si `ine`ou `nip`sont spécifiés, cherche les formsemestres dans
@ -647,19 +670,21 @@ informatique de 2014 en formation initiale (FI).
* **Exemple de résultat:** [formsemestres-query.json](samples/sample_formsemestres-query.json.md)
#### **etudiant-formsemestres**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `etudid`, `nip`, `ine`
* **Routes:** :
* `/etudiant/etudid/<int:etudid>/formsemestres` ou
* `/etudiant/nip/<string:nip>/formsemestres` ou
* `/etudiant/ine/<string:ine>/formsemestres`
* `/etudiant/etudid/<int:etudid>/formsemestres` ou
* `/etudiant/nip/<string:nip>/formsemestres` ou
* `/etudiant/ine/<string:ine>/formsemestres`
* **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres`
* **Résultat:** Liste des semestres qu'un étudiant a suivi, triés
par ordre chronologique.
* **Exemple de résultat:** [etudiant-formsemestres.json](samples/sample_etudiant-formsemestres.json.md)
#### **formsemestre**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`
@ -671,39 +696,49 @@ informatique de 2014 en formation initiale (FI).
### **API Groupe**
#### **`partition-group-create`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `partition_id`
* **Data:** `{ group_name : <string> }`
* **Routes:** `/partition/<int:partition_id>/create`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/create`
>`{ "group_name" : "A" }`
* **Résultat:** Crée un groupe dans une partition.
* **Exemple de résultat:** [partition-create.json](samples/sample_formsemestre-partition-create.json.md)
#### **`group-edit`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `group_id`
* **Data:** `{ group_name : <string> }`
* **Routes:** `/group/<int:group_id>/edit`
* **Exemple d'utilisation:** `/ScoDoc/api/group/4581/edit`
>`{ "group_name" : "nouveau" }`
* **Résultat:** Renomme un groupe.
* **Exemple de résultat:** [group-edit.json](samples/sample_group-edit.json.md)
#### **`partition-groups-order`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `partition_id`
* **Data:** `[ <int:group_id1>, <int:group_id2>, ... ]`
* **Routes:** `/partition/<int:partition_id>/groups/order`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/groups/order`
>`[ 4383, 4379, 4380, 4381, 4382, 4384 ]`
* **Résultat:** Spécifie l'ordre des groupes d'une partition.
* **Exemple de résultat:** [partition-groups-order.json](samples/sample_partition-groups-order.json.md)
#### **`group-delete`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `group_id`
@ -713,6 +748,7 @@ informatique de 2014 en formation initiale (FI).
* **Exemple de résultat:** [group-delete.json](samples/sample_group-delete.json.md)
#### **etudiant-formsemestre-groups**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine`
@ -725,6 +761,7 @@ informatique de 2014 en formation initiale (FI).
* **Exemple de résultat:** [etudiant-formsemestres-groups.json](samples/sample_etudiant-formsemestre-groups.json.md)
#### **`group-set_etudiant`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `group_id`, `etudid`
@ -734,6 +771,7 @@ informatique de 2014 en formation initiale (FI).
* **Exemple de résultat:** [groupes-set_etudiant.json](samples/sample_group-set_etudiant.json.md)
#### **`group-remove_etudiant`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`**
* **Paramètres:** `group_id`, `etudid`
@ -743,7 +781,9 @@ informatique de 2014 en formation initiale (FI).
* **Exemple de résultat:** [groupes-remove_etudiant.json](samples/sample_group-remove_etudiant.json.md)
### **API Jury**
#### **`formsemestre-decisions_jury`**
* **Permission: `ScoView`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
@ -772,6 +812,7 @@ responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut
| _**module**_ | Module | |
#### **`moduleimpl`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `moduleimpl_id`
@ -781,6 +822,7 @@ responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut
* **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl.json.md)
### **API Partition**
#### Structure Partition
L'ensemble des étudiants d'un semestre peut être réparti selon une ou
@ -799,6 +841,7 @@ d'un nombre quelconque de groupes d'étudiants.
| _**groups**_ | Group* | liste des groupes de la partition |
#### **`formsemestre-partitions`**
* **Méthode: GET**
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`
@ -808,6 +851,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Exemple de résultat:** [formsemestre-partitions.json](samples/sample_formsemestre-partitions.json.md)
#### **`partition`**
* **Méthode: GET**
* **Permission: `ScoView`**
* **Paramètres:** `partition_id`
@ -817,39 +861,49 @@ d'un nombre quelconque de groupes d'étudiants.
* **Exemple de résultat:** [partition.json](samples/sample_partition.json.md)
#### **`formsemestre-partition-create`**
* **Méthode: POST**
* **Permission: `ScoEtudsChangeGroups`**
* **Paramètres:** `formsemestre_id`
* **Data:** `{ "partition_name" : <string> }`
* **Routes:** `/formsemestre/<int:formsemestre_id>/partition/create`
>`{ "partition_name" : "PART" }`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/944/partition/create`
* **Résultat:** Crée une nouvelle partition dans un formsemestre.
* **Exemple de résultat:** [formsemestre-partition-create.json](samples/sample_formsemestre-partition-create.json.md)
#### **`partition-edit`**
* **Méthode: POST**
* **Permission: `ScoEtudsChangeGroups`**
* **Paramètres:** `partition_id`
* **Data:** `{ partition_name : <string> }`
* **Routes:** `/partition/<int:partition_id>/edit`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/2047/edit`
>`{ "partition_name" : "PART4" }`
* **Résultat:** Renomme une partition
* **Exemple de résultat:** [partition-edit.json](samples/sample_partition-edit.json.md)
#### **`formsemestre-partitions-order`**
* **Méthode: POST**
* **Permission: `ScoEtudsChangeGroups`**
* **Paramètres:** `formsemestre_id`
* **Data:** `[ <int:partition_id1>, <int:partition_id2>, ... ]`
* **Routes:** `/formsemestre/<int:formsemestre_id>/partitions/order`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/944/partitions/order`
>`[ 2048, 2054 ]`
* **Résultat:** Spécifie l'ordre des partitions d'un formsemestre.
* **Exemple de résultat:** [formsemestre-partitions-order.json](samples/sample_formsemestre-partitions-order.json.md)
#### **`partition-delete`**
* **Méthode: POST**
* **Permission: `ScoEtudsChangeGroups`**
* **Paramètres:** `partition_id`
@ -859,6 +913,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Exemple de résultat:** [partition-delete.json](samples/sample_partition-delete.json.md)
#### **`partition-remove_etudiant`**
* **Méthode: POST**
* **Permission: `ScoEtudsChangeGroups`**
* **Permission: `ScoEtudChangeGroups`**
@ -876,6 +931,7 @@ utilisateur pourra être associé à un ou plusieurs rôles dans chaque départe
d'un autre).
#### **roles**
* **Méthode:** GET
* **Permission: `ScoUsersView`**
* **Routes:** `/roles`
@ -884,6 +940,7 @@ d'un autre).
* **Exemple de résultat:** [roles.json](samples/sample_roles.json.md)
#### **role**
* **Méthode:** GET
* **Permission: `ScoUsersView`**
* **Routes:** `/role/<str:role_name>`
@ -892,6 +949,7 @@ d'un autre).
* **Exemple de résultat:** [role.json](samples/sample_role.json.md)
#### **role-add_permission**
* **Méthode: POST**
* **Permission: `ScoSuperAdmin`**
* **Routes:** `/role/<str:role_name>/add_permission/<str:perm_name>`
@ -901,44 +959,54 @@ d'un autre).
* **Exemple de résultat:** [role-add_permission.json](samples/sample_role-add_permission.json.md)
#### **role-remove_permission**
* **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.
Si le rôle n'a pas la permission, ne fait rien.
* **Exemple de résultat:** [role-remove_permission.json](samples/sample_role-remove_permission.json.md)
#### **role-create**
* **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.
* **Exemple de résultat:** [role-create.json](samples/sample_role-create.json.md)
#### **role-delete**
* **Méthode: POST**
* **Permission: `ScoSuperAdmin`**
* **Routes:** `/role/<str:role_name>/delete`
* **Exemple d'utilisation:** `/role/LaveurDeCarreaux/delete`
* **Résultat:** Supprime ce rôle.
* **Résultat:** Supprime ce rôle.
* **Exemple de résultat:** [role-delete.json](samples/sample_role-delete.json.md)
#### **role-edit**
* **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.
* **Exemple de résultat:** [role-edit.json](samples/sample_role-edit.json.md)
### **API User, Permissions**
#### **user**
* **Méthode:** GET
* **Permission: `ScoUsersView`**
* **Paramètres:** `user_id`
@ -948,9 +1016,11 @@ d'un autre).
* **Exemple de résultat:** [user.json](samples/sample_user.json.md)
#### **`user-create`**
* **Méthode: POST**
* **Permission: `ScoUsersAdmin`**
* **Data:**
* **Data:**
```json
{
"user_name": str,
@ -960,26 +1030,32 @@ d'un autre).
"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".
si est "super-administrateur".
* **Exemple de résultat:** [user-create.json](samples/sample_user-create.json.md)
#### **`users-query`**
* **Méthode:** GET
* **Permission: `ScoUsersView`**
* **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-query.json](samples/sample_users-query.json.md)
#### **`user-edit`**
* **Méthode: POST**
* **Permission: `ScoUsersAdmin`**
* **Data:**
```json
{
"dept": str or null,
@ -988,21 +1064,24 @@ d'un autre).
"active":bool (default True)
}
```
* **Routes:** `/user/<int:uid>/edit`
* **Résultat:** Modifie l'utilisateur d'UID indiqué.
* **Exemple de résultat:** [user-edit.json](samples/sample_user-edit.json.md)
#### **`user-password`**
* **Méthode: POST**
* **Permission: `ScoUsersAdmin`**
* **Data:** `{ "password": str }`
* **Routes:** `/user/<int:uid>/password`
* **Exemple d'utilisation:** `/user/3/password`
>`{ "password": "averycomplicatedpassaword" }
* **Résultat:** Modifie le mot de passe de l'utilisateur désigné par son UID.
L'opération peut être rejetée si le mot de passe ne satisfait pas les conditions requises (trop simple par exemple), avec le retour suivant:
>
> ```json
{
"error": "Bad Request",
@ -1014,6 +1093,7 @@ d'un autre).
* **Exemple de résultat:** [user-password.json](samples/sample_user-password.json.md)
#### **`user-role-add`**
* **Méthode: POST**
* **Permission: `ScoSuperAdmin`**
* **Routes:** `/user/<int:uid>/role/<str:role_name>/add[/departement/<string:dept_acronym>]`
@ -1022,6 +1102,7 @@ d'un autre).
* **Exemple de résultat:** [user-role-add.json](samples/sample_user-role-add.json.md)
#### **`user-role-remove`**
* **Méthode: POST**
* **Permission: `ScoUsersAdmin`**
* **Routes:** `/user/<int:uid>/role/<str:role_name>/remove[/departement/<string:dept_acronym>]`
@ -1029,6 +1110,7 @@ d'un autre).
* **Exemple de résultat:** [user-role-remove.json](samples/sample_user-role-remove.json.md)
#### **`permissions`**
* **Méthode:** GET
* **Permission: `ScoUsersView`**
* **Routes:** `/permissions`
@ -1038,7 +1120,9 @@ d'un autre).
* **Exemple de résultat:** [permissions.json](samples/sample_permissions.json.md)
### ** API Bulletin, Evaluations, Notes**
#### **formsemestre-bulletins**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`
@ -1048,10 +1132,11 @@ d'un autre).
* **Exemple de résultat:** [formsemestre-bulletins.json](samples/sample_formsemestre-bulletins.json.md)
#### **etudiant-formsemestre-bulletin**
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules
pour un formsemestre spécifié par son id.
Par défaut les valeurs numériques sont formattées en chaînes. Si format=raw, valeurs numériques
mais pas JSON compliant à cause des _NaN_.
mais pas JSON compliant à cause des `NaN`.
* **Méthode:** GET
* **Permission: `ScoView`**
@ -1063,26 +1148,33 @@ mais pas JSON compliant à cause des _NaN_.
ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]`
* **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin`
* **Résultat:** Bulletin de l'étudiant dans le formsemestre.
Deux types de variantes possibles:
Deux variantes possibles:
* versions `long` et `short` (`long`par défaut, ajoutez `/short` pour la version plus courte).
* version `json` et `pdf` (`json` par défaut, ajoutez `/pdf` pour la version pdf)
* version `json` et `pdf` (`json` par défaut, ajoutez `/pdf` pour la version
pdf)
* **Exemple de résultat:** [etudiant-formsemestre-bulletin.json](samples/sample_etudiant-formsemestre-bulletin.json.md)
#### **formsemestre-programme**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `dept`, `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/programme`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/programme`
* **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.
* **`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**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`
@ -1094,11 +1186,12 @@ mais pas JSON compliant à cause des _NaN_.
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules
pour un formsemestre spécifié par son id.
Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw,
valeurs numériques mais pas JSON compliant à cause des _NaN_.
valeurs numériques mais pas JSON compliant à cause des `NaN`.
* **Exemple de résultat:**
#### **`moduleimpl-evaluations`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `moduleimpl_id`
@ -1109,6 +1202,7 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:** [moduleimpl-evaluations.json](samples/sample_moduleimpl-evaluations.json.md)
#### **`evaluations-notes`**
* **Méthode**: GET
* **Permission: `ScoView`**
* **Paramètres**: `evaluation_id`
@ -1120,6 +1214,7 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:** [evaluation-notes.json](samples/sample_evaluation-notes.json.md)
#### **formsemestre-etat_evals**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formsemestre_id`
@ -1131,6 +1226,7 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
### **API Export, Référentiel**
#### **`formation-export`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formation_id`, `export_ids` (False par défaut. Ajouter `/with_ids` pour le passer à True)
@ -1142,16 +1238,19 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:** [formation-export.json](samples/sample_formation-export.json.md)
#### **`formation-referentiel_competences`**
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** `formation_id`
* **Routes:** `/formation/<int:formation_id>/referentiel_competences`
* **Exemple d'utilisation:** `api/formation/1/referentiel_competences`
* **Résultat:** Le référentiel de compétences d'une formation donnée (json). (_pas toujours présent_)
* **Résultat:** Le référentiel de compétences d'une formation donnée (json). (*pas toujours présent*)
* **Exemple de résultat:** [formation-referentiel_competences.json](samples/sample_formation-referentiel_competences.json.md)
### **API Logos**
#### **`logos`**
* **Méthode:** GET
* **Permission: `ScoSuperAdmin`**
* **Paramètres :** Aucun
@ -1161,6 +1260,7 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:** [logos.json](samples/sample_logos.json.md)
#### **`logo`**
* **Méthode:** GET
* **Permission: `ScoSuperAdmin`**
* **Paramètres :** Aucun
@ -1170,19 +1270,25 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:** [logo.json](samples/sample_logo.json.md)
#### **`departement-logos`**
* **Méthode:** GET
* **Permission: `ScoSuperAdmin`**
* **Paramètres:** Aucun
* **Route :**
* `/departement/<string:dept>/logos`
* `/departement/id/<int:departement_id>/logos`
* **Exemple d'utilisation :**
* `/departement/<string:dept>/logos`
* `/departement/id/<int:departement_id>/logos`
* `/departement/<string:dept>/logos`
* `/departement/id/<int:departement_id>/logos`
* **Exemple d'utilisation :**
* `/departement/<string:dept>/logos`
* `/departement/id/<int:departement_id>/logos`
* **Résultat :** Liste des noms des logos définis pour le département visé qui peut être désigné par son id ou par son acronyme (selon la forme de la route).
* **Exemple de résultat:** [departement-logos.json](samples/sample_departement-logos.json.md)
#### **`departement-logo`**
* **Méthode:** GET
* **Permission: `ScoSuperAdmin`**
* **Paramètres :** Aucun
@ -1190,14 +1296,17 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_.
* `/departement/<string:dept>/logo/<string:nom>`
* `/departement/id/<int:departement_id>/logo/<string:nom>`
* **Exemple d'utilisation:**
* `/ScoDoc/api/departement/MMI/logo/header`
* `/ScoDoc/api/departement/id/3/logo/header`
* **Résultat :** l'image (format png ou jpg)
* **Exemple de résultat:** [departement-logo.json](samples/sample_departement-logo.json.md)
-------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------
### En savoir plus
### En savoir plus
Voir exemples d'utilisation de l'API en Python, dans `tests/api/`.
## Fonctions de l'API ScoDoc 7 portées en ScoDoc 9
@ -1211,19 +1320,20 @@ disparaitront en juillet 2022.
Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.
- `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/ etudid>`)
- `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`)
- `Absences/XMLgetAbsEtud` (deviendra `api/absences/ etudid>`, en json)
- `Notes/evaluation_listenotes` (non existante en ScoDoc9, trop complexe)
- `Notes/formsemestre_id` (deviendra `api/formsemestre`)
- `Notes/formsemestre_bulletinetud` (deviendra `api/etud/<etudid>/bul/<formsemestre_id>`)
- `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?)
- `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/<etudid>`)
- `groups_view` (deviendra `groups`)
* `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/ etudid>`)
* `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`)
* `Absences/XMLgetAbsEtud` (deviendra `api/absences/ etudid>`, en json)
* `Notes/evaluation_listenotes` (non existante en ScoDoc9, trop complexe)
* `Notes/formsemestre_id` (deviendra `api/formsemestre`)
* `Notes/formsemestre_bulletinetud` (deviendra `api/etud/<etudid>/bul/<formsemestre_id>`)
* `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?)
* `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/<etudid>`)
* `groups_view` (deviendra `groups`)
Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est
à dire `https://votre.site.fr/ScoDoc/<dept>/Scolarite/`, et répondent en GET et
en POST.
Note:
- `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.

4
tools/publish
View File

@ -11,10 +11,10 @@ fi
# --- Build
if [ "$1" = "-b" ]
then
if [ "${CONDA_DEFAULT_ENV}" != "mkdocs" ]
if ! command -v mkdocs &> /dev/null
then
echo "Please active mkdocs :"
echo " conda activate mkdocs"
echo " source venv/bin/activate"
exit 1
fi
mkdocs build