From 6bb5d17741b7b8a9146bdda2a3b734afc8f2ac98 Mon Sep 17 00:00:00 2001 From: viennet Date: Sat, 16 Jul 2022 22:48:40 +0300 Subject: [PATCH] =?UTF-8?q?D=C3=A9but=20de=20mise=20=C3=A0=20jour=20doc=20?= =?UTF-8?q?API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ScoDoc9API.md | 218 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 173 insertions(+), 45 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index e30f70b..9f5adad 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -232,7 +232,7 @@ par le serveur ScoDoc. * **Méthode:** GET * **Paramètres:** `dept` * **Routes:** `/departement//formsemestres_ids` - * **Exemple d'utilisation:** `/api/departements/MMI/formsemestres_ids` + * **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_ids` * **Résultat:** Liste des id des formsemestres d'un département donné. * **Exemple de résultat:** ```[ 28, 99, 3 ]``` @@ -241,7 +241,7 @@ par le serveur ScoDoc. * **Méthode:** GET * **Paramètres:** `dept` * **Routes:** `/departement//formsemestres_courants` - * **Exemple d'utilisation:** `/api/departements/MMI/formsemestres_courants` + * **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_courants` * **Résultat:** Liste des formsemestres en cours d'un département donné. * **Exemple de résultat:** ``` @@ -316,7 +316,7 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le * **`etudiant`** * **Méthode:** GET * **Paramètres:** `etudid`, `nip`, `ine` - * **Routes:** `/etudiant/etudid/` ou `/etudiant/nip/` ou `/etudiant/ine/` + * **Routes:** `/etudiant/etudid/` ou `/etudiant/nip/` ou `/etudiant/ine/` * **Exemple d'utilisation:** `/api/etudiant/nip/1` * **Résultat:** Retourne les informations sur l'étudiant correspondant à l'id passé en paramètres. @@ -329,6 +329,8 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le "code_ine": "1", "code_nip": "1", "date_naissance": "", + "dept_id": 1, + "dept_acronym": "TAPI", "email": "SACHA.COSTA@example.com", "emailperso": "", "etudid": 1, @@ -354,21 +356,54 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le * **`etudiants`** * **Méthode:** GET * **Paramètres:** `etudid`, `nip`, `ine` - * **Routes:** `/etudiants/etudid/` ou `/etudiants/nip/` ou `/etudiants/ine/` + * **Routes:** `/etudiants/etudid/` ou `/etudiants/nip/` ou `/etudiants/ine/` * **Exemple d'utilisation:** `/api/etudiants/nip/1` - * **Résultat:** Info sur le ou les étudiants correspondant. + * **Résultat:** Info sur le ou les étudiants correspondants. Comme `/etudiant` mais renvoie toujours une liste. Si non trouvé, liste vide, pas d'erreur. Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a été inscrit dans plusieurs départements, on a plusieurs objets (1 par dept.). - + +* **Exemple de résultat:** + ``` + [ + { + "civilite": "X", + "code_ine": "1", + "code_nip": "1", + "date_naissance": "", + "dept_id": 1, + "dept_acronym": "TAPI", + "email": "SACHA.COSTA@example.com", + "emailperso": "", + "etudid": 1, + "nom": "COSTA", + "prenom": "SACHA", + "nomprenom": "Sacha COSTA", + "lieu_naissance": "", + "dept_naissance": "", + "nationalite": "", + "boursier": "", + "id": 1, + "codepostaldomicile": "", + "paysdomicile": "", + "telephonemobile": "", + "typeadresse": "domicile", + "domicile": "", + "villedomicile": "", + "telephone": "", + "fax": "", + "description": "" + } + ] + ``` #### Cursus * **`etudiant_formsemestres`** * **Méthode:** GET * **Paramètres:** `etudid`, `nip`, `ine` - * **Routes:** : `/etudiant/etudid//formsemestres` ou `/etudiant/nip//formsemestres` ou `/etudiant/ine//formsemestres` + * **Routes:** : `/etudiant/etudid//formsemestres` ou `/etudiant/nip//formsemestres` ou `/etudiant/ine//formsemestres` * **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres` * **Résultat:** Retourne la liste des semestres qu'un étudiant a suivis, triés par ordre chronologique. (json) * **Exemple de résultat:** @@ -414,11 +449,15 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le * **Méthode:** GET * **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` * **Routes:** - `/etudiant/etudid//formsemestre//bulletin` - ou `/etudiant/nip//formsemestre//bulletin` - ou `/etudiant/ine//formsemestre//bulletin` + `/etudiant/etudid//formsemestre//bulletin[/format][/pdf]` + ou `/etudiant/nip//formsemestre//bulletin[/format][/pdf]` + ou `/etudiant/ine//formsemestre//bulletin[/format][/pdf]` + + On peut spécifier le format: `long`ou `short`, et indiquer si l'on veut le + bulletin PDF. * **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin` * **Résultat:** Bulletin de l'étudiant dans le formsemestre. + Deux versions disponibles `long` et `short` (par défaut `long` ajoutez `/short` pour la version plus courte). * **Exemple de résultat:** ``` { @@ -595,7 +634,7 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le * **`etudiant_groups`** * **Méthode:** GET * **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` - * **Routes:** `/etudiant/etudid//semestre//groups` ou `/etudiant/nip//semestre//groups` ou `/etudiant/ine//semestre//groups` + * **Routes:** `/etudiant/etudid//semestre//groups` ou `/etudiant/nip//semestre//groups` ou `/etudiant/ine//semestre//groups` * **Exemple d'utilisation:** `/etudiant/nip/1/semestre/1/groups` * **Résultat:** Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json) * **Exemple de résultat:** @@ -638,12 +677,12 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le * **Exemple de résultat:** `[17, 99, 32]` - * **`formations_by_id`** + * **`formation`** * **Méthode:** GET * **Paramètres:** `formation_id` * **Routes:** `/formation/` * **Exemple d'utilisation:** `/ScoDoc/api/formation/1` - * **Résultat:** Retourne une formation en fonction d'un id donné + * **Résultat:** Retourne la formationd'id donné * **Exemple de résultat:** ``` { @@ -661,7 +700,7 @@ Le `titre`est celui donné par l'utilisateur dans le formsemestre, tandis que le } ``` #### Export programme - * **`formation_export_by_formation_id`** + * **`formation_export`** * **Méthode:** GET * **Paramètres:** `formation_id`, `export_ids` (False par défaut. Ajouter `/with_ids` pour le passer à True) * **Routes:** `/formation/formation_export/` @@ -804,9 +843,10 @@ Les sessions de formation (qu'elles durent une année ou un mois) sont représen ], "scodoc7_id": null, "semestre_id": 1, - "titre_court": "BUT MMI" + "titre_court": "BUT MMI", "titre_num": "Semestre test semestre 1", "titre": "Semestre test", + "session_id": "MMI-BUT-FI-S1-2021", } ``` * **`formsemestre_apo`** @@ -843,8 +883,10 @@ des informations suivantes: #### Étudiants inscrits * **etudiants** - * **Méthode:** GET - * **Routes:** `/formsemestre//etudiants` + * **Méthode:** GET + * **Paramètres:** `formsemestre_id`, `etat` (par défaut égal à "I" pour les étudiants inscrits) + * **Routes:** `/formsemestre//etudiants` XXX voir si + filtrage par état (dem, def, ...) * **Résultat:** les étudiants inscrits à ce semestres XXX préciser état (DEM, DEF)) @@ -1028,6 +1070,59 @@ des informations suivantes: } ] ``` + * **etat_evals** + * **Méthode:** GET + * **Paramètres:** `formsemestre_id` + * **Routes:** `/formsemestre//etat_evals` + * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/etat_evals` + * **Résultat:** Retourne les informations sur l'état des évaluations d'un semestre donnée + * **Exemple de résultat:** + ``` + { + "RT1.1": [ + { + "id": 1, + "titre": "Initiation aux réseaux informatiques", + "evaluations": [ + { + "id": 1, + "description": null, + "datetime_epreuve": null, + "heure_fin": "09:00:00", + "comptee": "oui", + "inscrits": 16, + "manquantes": 0, + "ABS": 0, + "ATT": 0, + "EXC": 0, + "saisie_notes": { + "datetime_debut": "2021-09-11T00:00:00+02:00", + "datetime_fin": "2022-08-25T00:00:00+02:00", + "datetime_mediane": "2022-03-19T00:00:00+01:00" + } + }, + { + "id": 22, + "description": null, + "datetime_epreuve": "2021-08-11T00:00:00+02:00", + "heure_fin": "08:00:00", + "comptee": "oui", + "inscrits": 16, + "manquantes": 0, + "ABS": 0, + "ATT": 0, + "EXC": 0, + "saisie_notes": { + "datetime_debut": "2021-09-11T00:00:00+02:00", + "datetime_fin": "2022-08-25T00:00:00+02:00", + "datetime_mediane": "2022-03-19T00:00:00+01:00" + } + }, + ] + }, + ] + } + ``` @@ -1190,15 +1285,53 @@ d'un nombre quelconque de groupes d'étudiants. ] ``` - * **`/partitions/groups/`** + * **`groups`** * **Méthode: GET** * **Paramètres:** `group_id`, `etat` * **Routes:** `/partitions/groups/` ou `/partitions/groups//etat/` * **Exemple d'utilisation:** `/ScoDoc/api/partitions/groups/1` - * **Résultat:** XXX à préciser + * **Résultat:** Retourne la liste des étudiants dans un groupe. * **Exemple de résultat:** ``` - + [ + { + "etudid": 10, + "id": 10, + "dept_id": 1, + "nom": "BOUTET", + "prenom": "Marguerite", + "nom_usuel": "", + "civilite": "F", + "date_naissance": null, + "lieu_naissance": null, + "dept_naissance": null, + "nationalite": null, + "statut": null, + "boursier": null, + "photo_filename": null, + "code_nip": "10", + "code_ine": "10", + "scodoc7_id": null, + "email": "MARGUERITE.BOUTET@example.com", + "emailperso": null, + "domicile": null, + "codepostaldomicile": null, + "villedomicile": null, + "paysdomicile": null, + "telephone": null, + "telephonemobile": null, + "fax": null, + "typeadresse": "domicile", + "description": null, + "group_id": 1, + "etat": "I", + "civilite_str": "Mme", + "nom_disp": "BOUTET", + "nomprenom": "Mme Marguerite BOUTET", + "ne": "e", + "email_default": "MARGUERITE.BOUTET@example.com" + } + ] ``` @@ -1243,14 +1376,14 @@ d'un nombre quelconque de groupes d'étudiants. ``` - * **`evaluation_notes`** + * **`evaluations/notes`** * **Méthode**: GET * **Paramètres**: `evaluation_id` * **Routes:** `/evaluations/eval_notes/` - * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_notes/1` - * **Résultat:** Retourne la liste des notes à partir de l'id d'une évaluation donnée + * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/notes/1` + * **Résultat:** Retourne la liste des notes d'une évaluation * **Exemple de résultat:** - XXX à revoir (à spécifier) + XXX à revoir (à spécifier/reprendre implémentation XXX was eval_notes) ### Absences @@ -1267,25 +1400,21 @@ d'un nombre quelconque de groupes d'étudiants. ``` [ { + "jour": "2022-04-15", "matin": true, "estabs": true, "estjust": true, - "description": "", + "description": "Retard bus", "begin": "2022-04-15 08:00:00", "end": "2022-04-15 11:59:59" }, { - "matin": false, - "estabs": true, - "estjust": false, - "description": "", - "begin": "2022-04-15 12:00:00", - "end": "2022-04-15 17:59:59" + ... } ] ``` - * **`absences_just`** + * **`absences/just`** * **Méthode:** GET * **Paramètres:** `etudid` * **Routes:** `/absences/etudid//just` @@ -1295,20 +1424,16 @@ d'un nombre quelconque de groupes d'étudiants. ``` [ { + "jour": "2022-04-15", "matin": true, "estabs": true, "estjust": true, - "description": "", + "description": "Retard bus", "begin": "2022-04-15 08:00:00", "end": "2022-04-15 11:59:59" }, { - "matin": false, - "estabs": true, - "estjust": true, - "description": "", - "begin": "2022-04-15 12:00:00", - "end": "2022-04-15 17:59:59" + ... } ] ``` @@ -1316,13 +1441,15 @@ d'un nombre quelconque de groupes d'étudiants. * **`abs_groupe_etat`** * **Méthode:** GET - * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html` + * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, * **Routes:** `/absences/abs_group_etat/` ou `/absences/abs_group_etat/group_id//date_debut//date_fin/` * **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/1` - * **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates. + * **Résultat:** Liste des absences d'un groupe entre deux dates. * **Exemple de résultat:** ``` - XXX A COMPLETER + XXX A COMPLETER XXX with_boursier ?? + + * XXX ajouter méthode(s) de set abs ``` @@ -1355,11 +1482,12 @@ d'un nombre quelconque de groupes d'étudiants. * **`liste des logos globaux`** * **Méthode:** GET * **Paramètres:** `format` (json, xml), json par défaut - * **Route :** `/logos` + * **Route :** `/ScoDoc/api/logos` * **Exemple d'utilisation :** `/ScoDoc/api/logos?format=xml` - * **Résultat :** Liste des logos définis pour le site scodoc. + * **Résultat :** Liste des noms des logos définis pour le site scodoc. * **Exemple de résultat:** `['header', 'footer', 'custom']` + XXX vérifier si on supporte XML et pour qui ? * **`récupération d'un logo global`** * **Méthode:** GET @@ -1374,7 +1502,7 @@ d'un nombre quelconque de groupes d'étudiants. * **Paramètres:** `format` (json, xml) * **Route :** `/departements//logos` * **Exemple d'utilisation :** `/ScoDoc/api/departements/MMI/logos` - * **Résultat :** Liste des logos définis pour le département visé. + * **Résultat :** Liste des noms des logos définis pour le département visé. * **Exemple de résultat:** `['footer', 'signature', 'universite']`