From 0291669255a2bbb8fd85d6069900010fbe9ac107 Mon Sep 17 00:00:00 2001 From: viennet Date: Sat, 29 Oct 2022 09:16:14 +0200 Subject: [PATCH] Formattage doc API --- README.md | 21 ++++ docs/ScoDoc9API.md | 232 +++++++++++++++++++++++++++++++++------------ tools/publish | 4 +- 3 files changed, 194 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index d142de2..83ab45a 100644 --- a/README.md +++ b/README.md @@ -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 +``` diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 6bfb677..916d940 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -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/` - * `/departement/` + * `/departement/id/` + * `/departement/` * **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//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//etudiants/long` * `/formsemestre//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//etudiants` - * `/group//etudiants/query` + * `/group//etudiants` + * `/group//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//formsemestres_ids` - * `/departement//formsemestres_ids` + * `/departement/id//formsemestres_ids` + * `/departement//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//formsemestres` ou - * `/etudiant/nip//formsemestres` ou - * `/etudiant/ine//formsemestres` + * `/etudiant/etudid//formsemestres` ou + * `/etudiant/nip//formsemestres` ou + * `/etudiant/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 : }` * **Routes:** `/partition//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 : }` * **Routes:** `/group//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:** `[ , , ... ]` * **Routes:** `/partition//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" : }` * **Routes:** `/formsemestre//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 : }` * **Routes:** `/partition//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:** `[ , , ... ]` * **Routes:** `/formsemestre//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/` @@ -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//add_permission/` @@ -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//remove_permission/` * **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/` * **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//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/` * **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=` + * **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//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//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//role//add[/departement/]` @@ -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//role//remove[/departement/]` @@ -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//formsemestre//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//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//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//logos` - * `/departement/id//logos` -* **Exemple d'utilisation :** - * `/departement//logos` - * `/departement/id//logos` + + * `/departement//logos` + * `/departement/id//logos` + +* **Exemple d'utilisation :** + + * `/departement//logos` + * `/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//logo/` * `/departement/id//logo/` * **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//bul/`) - - `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) - - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/`) - - `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//bul/`) +* `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) +* `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/`) +* `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//Scolarite/`, et répondent en GET et en POST. Note: + - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API. diff --git a/tools/publish b/tools/publish index cfc909b..efcbbad 100755 --- a/tools/publish +++ b/tools/publish @@ -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