From 72e5d2401a9a968c7de5492f9b49559bc07535f0 Mon Sep 17 00:00:00 2001 From: leonard_montalbano Date: Fri, 31 Dec 2021 11:29:27 +0100 Subject: [PATCH] =?UTF-8?q?correctifs=20sur=20diff=C3=A9rents=20points=20d?= =?UTF-8?q?e=20la=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ScoDoc9API.md | 124 +++++++++++++++++++++++---------------------- 1 file changed, 63 insertions(+), 61 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 6bc9b75..7b547cf 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -35,14 +35,14 @@ 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/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/`) - `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/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/`) + - `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 @@ -62,6 +62,8 @@ La documentation ci-dessous concerne la **future** version De ScoDoc. Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction +L'ensemble des routes sont visible via la commande suivante : ``flask routes | grep /ScoDoc/api`` + ### Authentification TODO décrire procédure d'authentification et tokens jwt. @@ -88,42 +90,42 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`departements`** * **Méthode:** GET * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessibles à l'utilisateur courant), `format` (json, xml) - * **Routes:** `/api/departements` - * **Exemple d'utilisation:** `/api/departements` + * **Routes:** `/ScoDoc/api/departements` + * **Exemple d'utilisation:** `/ScoDoc/api/departements` * **Résultat:** Liste des id de départements. * **Exemple de résultat:** `[id_1, id_2, id_3, ...]` * **`liste_etudiants`** * **Méthode:** GET - * **Paramètres:** `dept`, `semestre` - * **Routes:** `/api/departements//etudiants/liste/` (_`semestre` étant un paramètre optionnel_) - * **Exemple d'utilisation:** `/api/departements/MMI/etudiants/liste` - * **Résultat:** liste des étudiants d'un département - semestre actuel par défaut. + * **Paramètres:** `dept`, `formsemestre_id` + * **Routes:** `/ScoDoc/api/departements//etudiants/liste/` (_`semestre` étant un paramètre optionnel_) + * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/etudiants/liste` + * **Résultat:** Liste des étudiants d'un département - semestre actuel par défaut. * **`liste_semestres_actifs`** * **Méthode:** GET * **Paramètres:** `dept` - * **Routes:** `/api/departements//semestres_actifs` - * **Exemple d'utilisation:** `/api/departements/MMI/semestres_actifs` + * **Routes:** `/ScoDoc/api/departements//semestres_actifs` + * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/semestres_actifs` * **Résultat:** Liste des semestres actifs d'un département donné. (_réponse sous format json_) * **`referenciel_competences`** * **Méthode:** GET * **Paramètres:** `dept`, `formation` (_`formation` étant un id de formation, un programme pédagogique_) - * **Routes:** `/api/departements//formations//referentiel_competences` - * **Exemple d'utilisation:** `/api/departements/MMI/formations/12/referentiel_competences` - * **Résultat:** Le référentiel de compétences d'une formation donnée. (_pas toujours présent_) + * **Routes:** `/ScoDoc/api/departements//formations//referentiel_competences` + * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/formations/12/referentiel_competences` + * **Résultat:** Le référentiel de compétences d'une formation donnée au format json. (_pas toujours présent_) ## Etudiants * **`etud_dept`** * **Méthode:** GET * **Paramètres:** `code_nip` - * **Routes:** `/api/etud_dept/` - * **Exemple d'utilisation:** `/api/etud_dept/123` + * **Routes:** `/ScoDoc/api/etud_dept/` + * **Exemple d'utilisation:** `/ScoDoc/api/etud_dept/123` * **Résultat:** Liste des étudiants avec le code NIP donné tirée par ordre d'inscription décroissant. * **Exemple de résultat:** ``` @@ -141,8 +143,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`etudiant`** * **Méthode:** GET * **Paramètres:** `etudid` - * **Routes:** `/api/etudiant/` - * **Exemple d'utilisation:** `/api/etudiant/987` + * **Routes:** `/ScoDoc/api/etudiant/` + * **Exemple d'utilisation:** `/ScoDoc/api/etudiant/987` * **Résultat:** Un dictionnaire avec les informations de l'étudiant correspondant à l'id passé en paramètres. * **Exemple de résultat:** ``` @@ -178,8 +180,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`etudiant_bulletin_semestre`** * **Méthode:** GET * **Paramètres:** `etudid`, `sem_id` - * **Routes:** `/api/etudiant//semestre//bulletin` - * **Exemple d'utilisation:** `/api/etudiant/987/semestre/12/bulletin` + * **Routes:** `/ScoDoc/api/etudiant//semestre//bulletin` + * **Exemple d'utilisation:** `/ScoDoc/api/etudiant/987/semestre/12/bulletin` * **Résultat:** Le bulletin d'un étudiant en fonction de son id et d'un semestre donné. * **Exemple de résultat:** voir plus bas sur cette page. @@ -189,8 +191,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`etudiant_bulletin`** * **Méthode:** GET * **Paramètres:** `formsemestre_id`, `dept`, `etudid`, `format` (`pdf` ou `json` _par défaut json_), `version` (`short`, `selectedevals` ou `long`) - * **Routes:** : `/api/formsemestre//departements//etudiant/nip|id|ine/{NIP}|{etudid}|numScodoc}/releve` - * **Exemple d'utilisation:** `/api/formsemestre/123/departements/MMI/etudiant/id/456/releve?format=pdf&version=short` + * **Routes:** : `/ScoDoc/api/formsemestre//departements//etudiant/nip|id|ine/{NIP}|{etudid}|numScodoc}/bulletin?format=&version=` + * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/123/departements/MMI/etudiant/id/456/bulletin?format=pdf&version=short` * **Résultat:** Un bulletin de notes. * **Exemple de résultat:** ici au format JSON, pour une version courte (`version=short`) ``` @@ -360,16 +362,16 @@ formsemestre_id": "SEM12345", * **`etudiant_photo`** * **Méthode:** GET * **Paramètres:** `etudid`, `small` - * **Routes:** `/api/etudiant//photo` **OU** `/api/etudiant//photo/small` (_ajout du paramètre **small** pour la version small_) - * **Exemple d'utilisation:** `/api/etudiant/123/photo` **OU** `/api/etudiant/123/photo/small` (_pour la version small_) + * **Routes:** `/ScoDoc/api/etudiant//photo` **OU** `/ScoDoc/api/etudiant//photo/small` (_ajout du paramètre **small** pour la version small_) + * **Exemple d'utilisation:** `/ScoDoc/api/etudiant/123/photo` **OU** `/ScoDoc/api/etudiant/123/photo/small` (_pour la version small_) * **Résultat:** Image en JPEG ou PNG. * **`etudiant_groups`** * **Méthode:** GET * **Paramètres:** `etudid`, `formsemestre_id` - * **Routes:** `/api/etudiant//semestre//groups` - * **Exemple d'utilisation:** `/api/etudiants/123/semestre/INFO-DUT-FI-S1-2014/groups` + * **Routes:** `/ScoDoc/api/etudiant//semestre//groups` + * **Exemple d'utilisation:** `/ScoDoc/api/etudiants/123/semestre/INFO-DUT-FI-S1-2014/groups` * **Résultat:** Liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. ``` @@ -400,8 +402,8 @@ formsemestre_id": "SEM12345", * **`formations`** * **Méthode:** GET * **Paramètres:** `formation_id` (_optionnel, si absent, liste toutes les formations_) - * **Routes:** `/api/formations` **ou** `/api/formations/` - * **Exemple d'utilisation:** `/api/formations` **ou** `/api/formations/1` + * **Routes:** `/ScoDoc/api/formations` **ou** `/ScoDoc/api/formations/` + * **Exemple d'utilisation:** `/ScoDoc/api/formations` **ou** `/ScoDoc/api/formations/1` * **Résultat:** Liste des formations. * **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]` * TODO: détailler le contenu publié @@ -411,8 +413,8 @@ formsemestre_id": "SEM12345", * **`formation_export`** * **Méthode:** GET * **Paramètres:** `formation_id`, `export_ids` (_par défaut "faux"_) - * **Routes:** `/api/formations/formation_export/` - * **Exemple d'utilisation:** `/api/formations/formation_export/596` **ou** `/api/formations/formation_export/596?format=xml&export_ids=1` + * **Routes:** `/ScoDoc/api/formations/formation_export/?format=&export_ids=` + * **Exemple d'utilisation:** `/ScoDoc/api/formations/formation_export/596` **ou** `/ScoDoc/api/formations/formation_export/596?format=xml&export_ids=1` * **Résultat:** La formation, avec UE, matières, modules (_un arbre_). * **Exemple de résultat:** ``` @@ -432,8 +434,8 @@ formsemestre_id": "SEM12345", * **`UEs`** * **Méthode:** GET * **Paramètres:** `dept`, `̀semestre` - * **Routes:** `/api/departements//formations/programme/` - * **Exemple d'utilisation:** `̀/api/departements/MMI/formations/programme/INFO-DUT-FI-S1-2014` + * **Routes:** `/ScoDoc/api/departements//formations/programme/` + * **Exemple d'utilisation:** `̀/ScoDoc/api/departements/MMI/formations/programme/INFO-DUT-FI-S1-2014` * **Résultat:** Liste des UEs, ressources et SAE d'un semestre @@ -445,8 +447,8 @@ Les sessions de formation (dénommées "semestres" même si elles durent une ann * **`formsemestre`** * **Méthode:** GET * **Paramètres:** `formsemestre_id` ou `etape_apo`, `format`(json ou xml) - * **Routes:** `/api/formations/formsemestre/`, `/api/formsemestre/apo/` - * **Exemple d'utilisation:** `/api/formations/formsemestre/12` + * **Routes:** `/ScoDoc/api/formations/formsemestre/`, `/ScoDoc/api/formsemestre/apo/` + * **Exemple d'utilisation:** `/ScoDoc/api/formations/formsemestre/12` * **Résultat:** Informations sur le(s) formsemestre(s). * **Exemple de résultat:** ``` @@ -497,7 +499,7 @@ On peut récupérer soit un module par son id, soit la listes des modules d'un s * **`moduleimpl`** * **Méthode:** GET * **Paramètres**: `formsemestre_id` ou `moduleimpl_id` - * **Routes:** `/api/formations/moduleimpl/` **ou** `/api/formations/moduleimpl//formsemestre/` + * **Routes:** `/ScoDoc/api/formations/moduleimpl/` **ou** `/ScoDoc/api/formations/moduleimpl//formsemestre/` * **Résultat:** liste de moduleimpl * **Exemple de résultat:** TODO @@ -515,8 +517,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`partition`** * **Méthode: GET** * **Paramètres:** `formsemestre_id` - * **Routes:** `/api/partitions/` - * **Exemple d'utilisation:** `/api/partition/48` + * **Routes:** `/ScoDoc/api/partitions/` + * **Exemple d'utilisation:** `/ScoDoc/api/partition/48` * **Résultat:** La liste de toutes les partitions d'un formsemestre. * **Exemple de résultat:** ``` @@ -571,10 +573,10 @@ d'un nombre quelconque de groupes d'étudiants. * **`groups`** * **Méthode:** GET * **Paramètres:** `formsemestre_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I` - * **Routes:** `api/partitions/formsemestre//groups/group_ids?with_codes=0|1&all_groups=0|1&etat=None|I` - * **Exemple d'utilisation:** `api/partitions/formsemestre/213/groups/123?with_codes=1` + * **Routes:** `/ScoDoc/api/partitions/formsemestre//groups/group_ids?with_codes=&all_groups=&etat=None|I` + * **Exemple d'utilisation:** `/ScoDoc/api/partitions/formsemestre/213/groups/123?with_codes=True` * **Résultat:** Liste des étudiants dans un groupe. - * **Exemple de résultat au format XML:** (_avec `with_codes=1`_) + * **Exemple de résultat au format XML:** (_avec `with_codes=True`_) ``` @@ -607,7 +609,7 @@ d'un nombre quelconque de groupes d'étudiants. "etat":"I", "emailperso":null, "prenom":"Dalil", - "nom_disp":"CLINTO", + "nom_disp":"CLINTO",? "email":"xxx@example.com", "62029":"A", "62032":null, @@ -633,8 +635,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`set_groups`** * **Méthode:** POST * **Paramètres:** `partition_id`, `groups`, `groups_to_delete`, `groups_to_create` - * **Routes:** `/api/partitions/set_groups?partition_id=&groups=&groups_to_delete=&groups_to_create=` - * **Exemple d'utilisation:** `/api/partitions/set_groups?partition_id=65&groups=77&groups_to_delete=8&groups_to_create=4` + * **Routes:** `/ScoDoc/api/partitions/set_groups?partition_id=&groups=&groups_to_delete=&groups_to_create=` + * **Exemple d'utilisation:** `/ScoDoc/api/partitions/set_groups?partition_id=65&groups=77&groups_to_delete=8&groups_to_create=4` * **Résultat:** Set les groups. TODO: à changer, passer les paramètres dans le corps de la requête @@ -644,8 +646,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`evaluations`** * **Méthode:** GET * **Paramètres:** `moduleimpl_id` - * **Routes:** `/api/evaluations/` - * **Exemple d'utilisation:** `/api/evaluations/54` + * **Routes:** `/ScoDoc/api/evaluations/` + * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/54` * **Résultat:** Liste des évaluations à partir de l'id d'un moduleimpl. * **Exemple de résultat:** `[eval_1, eval_2, eval_3, ...]` @@ -653,8 +655,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`evaluation_notes`** * **Méthode**: GET * **Paramètres**: `evaluation_id` - * **Routes:** `/api/evaluations/eval_notes/` - * **Exemple d'utilisation:** `/api/evaluations/eval_notes/24` + * **Routes:** `/ScoDoc/api/evaluations/eval_notes/` + * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_notes/24` * **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée. * **Exemple de résultat:** ``` @@ -672,8 +674,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`evaluation_set_notes`** * **Méthode:** POST * **Paramètres:** `eval_id`, `etudid`, `note` - * **Routes:** `/api/evaluations/eval_set_notes?eval_id= etudid=¬e=` - * **Exemple d'utilisation:** `/api/evaluations/eval_set_notes?eval_id=6 etudid=456¬e=15` + * **Routes:** `/ScoDoc/api/evaluations/eval_set_notes?eval_id=&etudid=¬e=` + * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_set_notes?eval_id=6&etudid=456¬e=15` * **Résultat:** Set les notes d'une évaluation pour un étudiant donné. TODO vérifier et passer les valeurs dans le corps. @@ -685,8 +687,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`absences`** * **Méthode:** GET * **Paramètres:** `etudid`, `abs_just_only, format`, `abs_just_only` (_spécifie si on veut les absences justifiées ou non_). - * **Routes:** `/api/absences/` - * **Exemple d'utilisation:** `/api/absences/54` + * **Routes:** `/ScoDoc/api/absences/` + * **Exemple d'utilisation:** `/ScoDoc/api/absences/54` * **Résultat:** Liste des absences d'un étudiant donné. * **Exemple de résultat:** ```{jour: "2021-02-10", ampm: "0", description: "M2202", }``` (_**ampm** vaut 1 le matin et 0 l'après-midi_). @@ -719,8 +721,8 @@ 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` - * **Routes:** `/api/absences/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin` - * **Exemple d'utilisation:** `/api/absences/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30` + * **Routes:** `/ScoDoc/api/absences/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin` + * **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30` * **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates. * **Exemple de résultat:** si `format="json"` cela donne: ``` @@ -743,8 +745,8 @@ 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 :** `/api/logos` - * **Exemple d'utilisation :** `/api/logos?format=xml` + * **Route :** `/ScoDoc/api/logos` + * **Exemple d'utilisation :** `/ScoDoc/api/logos?format=xml` * **Résultat :** Liste des logos définis pour le site scodoc. * **Exemple de résultat:** `['header', 'footer', 'custom']` @@ -752,16 +754,16 @@ d'un nombre quelconque de groupes d'étudiants. * **`récupération d'un logo global`** * **Méthode:** GET * **Paramètres :** Aucun - * **Route:** `/api/logos/` - * **Exemple d'utilisation :** `/api/logos/header` + * **Route:** `/ScoDoc/api/logos/` + * **Exemple d'utilisation :** `/ScoDoc/api/logos/header` * **Résultat :** l'image (format png ou jpg) * **`logo d'un département`** * **Méthode:** GET * **Paramètres:** `format` (json, xml) - * **Route :** `/api/departements//logos` - * **Exemple d'utilisation :** `/api/MMI/logos` + * **Route :** `/ScoDoc/api/departements//logos` + * **Exemple d'utilisation :** `/ScoDoc/api/MMI/logos` * **Résultat :** Liste des logos définis pour le département visé. * **Exemple de résultat:** `['footer', 'signature', 'universite']` @@ -769,8 +771,8 @@ d'un nombre quelconque de groupes d'étudiants. * **`récupération d'un logo global`** * **Méthode:** GET * **Paramètres :** Aucun - * **Route:** `/api/departements//logos/` - * **Exemple d'utilisation:** `/api/departements/MMI/logos/header` + * **Route:** `/ScoDoc/api/departements//logos/` + * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/logos/header` * **Résultat :** l'image (format png ou jpg)