From 31458fccdf3620924b47a9394064f4a67307c8cb Mon Sep 17 00:00:00 2001 From: leonard_montalbano Date: Tue, 21 Dec 2021 15:56:23 +0100 Subject: [PATCH 1/2] =?UTF-8?q?modification=20suite=20=C3=A0=20la=20r?= =?UTF-8?q?=C3=A9union=20du=2020/12/2021?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ScoDoc9API.md | 1206 ++++++++++++++------------------------------ 1 file changed, 382 insertions(+), 824 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 22be35776..6bc9b7547 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -65,6 +65,9 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio ### Authentification TODO décrire procédure d'authentification et tokens jwt. +Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il vous sera attribué un token jwt (_généré automatiquement_) vous permettant d'utiliser l'api suivant les droits correspondant à votre session. + + ### Codes HTTP Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès. @@ -82,14 +85,38 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ ## Départements - * **`departement`** + * **`departements`** * **Méthode:** GET - * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessible à l'utilisateur courant), `format` (json, xml) - * **Routes:** `/api/departement` - * **Exemple d'utilisation:** `/api/departement` + * **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` * **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. + + + * **`liste_semestres_actifs`** + * **Méthode:** GET + * **Paramètres:** `dept` + * **Routes:** `/api/departements//semestres_actifs` + * **Exemple d'utilisation:** `/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_) + ## Etudiants * **`etud_dept`** @@ -111,11 +138,11 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ ``` - * **`etud`** + * **`etudiant`** * **Méthode:** GET - * **Paramètres:** etudid - * **Routes:** `/api/etud/` - * **Exemple d'utilisation:** `/api/etud/987` + * **Paramètres:** `etudid` + * **Routes:** `/api/etudiant/` + * **Exemple d'utilisation:** `/api/etudiant/987` * **Résultat:** Un dictionnaire avec les informations de l'étudiant correspondant à l'id passé en paramètres. * **Exemple de résultat:** ``` @@ -148,336 +175,22 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ ``` - * **`etud//bul`** + * **`etudiant_bulletin_semestre`** * **Méthode:** GET * **Paramètres:** `etudid`, `sem_id` - * **Routes:** `/api/etud//bul/` - * **Exemple d'utilisation:** `/api/etud/987/bul/12` + * **Routes:** `/api/etudiant//semestre//bulletin` + * **Exemple d'utilisation:** `/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. Voir aussi [Bulletins par défaut](https://scodoc.org/ParametrageBulletins/#exemple-1-bulletins-par-defaut) - - * **`etud//photo`** + * **`etudiant_bulletin`** * **Méthode:** GET - * **Paramètres:** `etudid`, `small` - * **Routes:** `/api/etud//photo` **OU** `/api/etud//photo/small` (_ajout du paramètre **small** pour la version small_) - * **Exemple d'utilisation:** `/api/etud/123/photo` **OU** `/api/etud/123/photo/small` (_pour la version small_) - * **Résultat:** Image en JPEG ou PNG. - - * **`etud//sem//groups`** - * **Méthode:** GET - * **Paramètres:** `etudid`, `formsemestre_id` - * **Routes:** `/api/etud//sem//groups` - * **Exemple d'utilisation:** `/api/etud/123/groups` - * **Résultat:** liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. - - Note: basé sur proposition de Seb., voir si on fusionne avec `/etud` pour tout fournir d'un coup ? -``` -{ - "etudid" : 1234, - "formsemestre_id" : 5678, - "groupes" : [ - { - "numero": 1, // Ordre d'affichage dans Scodoc - "partition_id": 62028, - "partition_name": "TD", - "group_id" : 1899, - "group_name": "TD 1" - },{ - "numero": 2, - "partition_id": 62029, - "partition_name": "TP", - "group_id" : 1905, - "group_name": "TP 2" - } - ] -} -``` - -## Programmes de formations - * **`formation`** - * **Méthode:** GET - * **Paramètres:** `formation_id` (_optionnel, si absent liste toutes les formations_) - * **Routes:** `/api/formation` **ou** `/api/formation/` - * **Exemple d'utilisation:** `/api/formation` **ou** `/api/formation/1` - * **Résultat:** Liste des formations. - * **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]` - * TODO: détailler le contenu publié - - - - * **`formation_export`** - * **Méthode:** GET - * **Paramètres:** `formation_id`, `export_ids` (_par défaut "faux"_) - * **Routes:** `/api/formation_export/` - * **Exemple d'utilisation:** `/api/formation_export/596` **ou** `/api/formation_export/596?format=xml&export_ids=1` - * **Résultat:** La formation, avec UE, matières, modules (_un arbre_). - * **Exemple de résultat:** -``` - { - "nom": "formation", - "UE": "ue", - "matieres": [ - "matiere_1": "maths", - "matiere_2": "anglais", - ... - ], - "modules": ... - } -``` - -## UE - -... TODO - - - - -## Semestres de formation -Les sessions de formation (dénommées "semestres" même si elles durent une année ou un mois) sont représentées par les `formsemestre`. - - * **`formsemestre`** - * **Méthode:** GET - * **Paramètres:** `formsemestre_id` ou `etape_apo`, `format`(json ou xml) - * **Routes:** `/api/formsemestre/`, `/api/formsemestre/apo/` - * **Exemple d'utilisation:** `/api/formsemestre/12` - * **Résultat:** Informations sur le(s) formsemestre(s). - * **Exemple de résultat:** -``` -[ - { - "annee_scolaire": "2022 - 2023", - "date_debut": "2022-09-01", - "date_fin": "2023-02-02", - "modalite": "FI", - "periode": 1, - "semestre_idx_txt": "S3", - "semestre_idx" : 3, - "session_id" : "GEII-BUT-FI-S3-2022", - "titre_annee": "BUT Génie Electrique et Informatique Industrielle semestre 3 FI 2021-2022" - "titre_num": "BUT Génie Electrique et Informatique Industrielle semestre 3", - "titre": "BUT Génie Electrique et Informatique Industrielle", - "parcours_type": XXX type de parcours - 'formation_id": 87, - } -] -``` - -### Note sur les identifiants de sessions -Le `session_id` peut être utilisé pour identifier de façon prévisible et -(presque) unique une session dans un établissement, ce qui est utile -notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois -du temps ou de services d'enseignement). Cet identifiant est constitué des -informations suivantes: - - * **Département** (RT, GEII, INFO...) (= paramètre `DeptName`, en majuscules) - * **Nom parcours:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME) - * **Modalité:** FI, FC, FA - * **"Spécialité":** S1 (ou S1D pour les semestres décalés), ou le - `code_specialite` si pas de semestres. Le code spécialité est un champ - (libre) nouveau dans la "formation" (programme pédagogique). - * **Année:** année de début de l'année scolaire correspondante (2014 pour - 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) - - -## Modules de formation -Les moduleimpl sont les modules d'un semestre, ou les ressources, ou les SAÉs. -On peut récupérer soit un module par son id, soit la listes des modules d'un semestre. - - * **`moduleimpl`** - * **Méthode:** GET - * **Paramètres**: `formsemestre_id` ou `moduleimpl_id` - * **Routes:** `/api/moduleimpl/`, `/api//formsemestre/` - * **Résultat:** liste de moduleimpl - * **Exemple de résultat:** - TODO - - - - - -## Groupes et partitions - -L'ensemble des étudiants d'un semestre peut être réparti selon une ou -plusieurs partitions (types de groupes). Chaque partition est constituée -d'un nombre quelconque de groupes d'étudiants. - - * **`partition`** - * **Méthode: GET** - * **Paramètres:** `formsemestre_id` - * **Routes:** `/api/partition/` - * **Exemple d'utilisation:** `/api/partition/48` - * **Résultat:** La liste de toutes les partitions d'un formsemestre. - * **Exemple de résultat:** -``` -[ - { - "formsemestre_id":"12781", - "partition_id":"23840", - "partition_name":"TD""group":[ - { - "formsemestre_id":"12781", - "partition_id":"23840", - "group_name":"A", - "group_id":"23841", - "partition_name":"TD" - }, - { - "formsemestre_id":"12781", - "partition_id":"23840", - "group_name":"B", - "group_id":"23843", - "partition_name":"TD" - } - ] - }, - { - "formsemestre_id":"12781", - "partition_id":"23941", - "partition_name":"TP""group":[ - { - "..." - }, - "..." - ] - }, - { - "formsemestre_id":"12781", - "partition_id":"22833", - "partition_name":null"group":[ - { - "formsemestre_id":"12781", - "partition_id":"22833", - "group_name":null, - "group_id":"G22834", - "partition_name":null - } - ] - } -] -``` - - * **`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:** - * **Exemple d'utilisation:** - * **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 JSON:** -``` -[ - { - "etat":"I", - "emailperso":null, - "prenom":"Dalil", - "nom_disp":"CLINTO", - "email":"xxx@example.com", - "62029":"A", - "62032":null, - "62031":"G1", - "62030":"A1" - }, - { - "etat":"I", - "emailperso":null, - "prenom":"Georges", - "nom_disp":"BUSH", - "email":"bush@example.com", - "62029":"A", - "62032":null, - "62031":"G1", - "62030":"A1" - }, - ... -] -``` - - * **`set_groups`** - * **Méthode:** POST - * **Paramètres:** `partition_id`, `groups`, `groups_to_delete`, `groups_to_create` - * **Routes:** `/api/set_groups?partition_id=&groups=&groups_to_delete=&groups_to_create=` - * **Exemple d'utilisation:** `/api/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 - - -## Bulletins de notes - * **`evaluations`** - * **Méthode:** GET - * **Paramètres:** `moduleimpl_id` - * **Routes:** `/api/evaluations/` - * **Exemple d'utilisation:** `/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, ...]` - - - * **`evaluation_notes`** - * **Méthode**: GET - * **Paramètres**: `evaluation_id` - * **Routes:** `/api/eval_notes/` - * **Exemple d'utilisation:** `/api/eval_notes/24` - * **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée. - * **Exemple de résultat:** -``` -[ - { - "84": "13", - "85": "15", - "86": "9", - ... - } -] -``` - - - * **`evaluation_set_notes`** - * **Méthode:** POST - * **Paramètres:** `eval_id`, `etudid`, `note` - * **Routes:** `/api/eval_set_notes?eval_id= etudid=¬e=` - * **Exemple d'utilisation:** `/api/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. - - - * **`etud//bul`** - * **Méthode:** GET - * **Paramètres:** `formsemestre_id`, `etudid`, `format` (`xml`ou `json`), `version` (`short`, `selectedevals` ou `long`) - * **Routes:** - * **Exemple d'utilisation:** + * **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` * **Résultat:** Un bulletin de notes. * **Exemple de résultat:** ici au format JSON, pour une version courte (`version=short`) ``` @@ -565,30 +278,8 @@ d'un nombre quelconque de groupes d'étudiants. "group_type": "TP", "group_name": "B1" }, - { - "ninscrits": 4, - "value": "1", - "group_type": "G", - "group_name": "G4" - }, - { - "ninscrits": "", - "value": "", - "group_type": "tutorat", - "group_name": "" - }, - { - "ninscrits": "", - "value": "", - "group_type": "App", - "group_name": "" - }, - { - "ninscrits": "", - "value": "", - "group_type": "sport", - "group_name": "" - } + ... + ], formsemestre_id": "SEM12345", "etape_apo": "V1RT", @@ -628,7 +319,6 @@ formsemestre_id": "SEM12345", }, "titre": "Initiation aux r\u00e9seaux d'entreprises", "evaluation": [ - ], "id": "27427" }, @@ -636,456 +326,13 @@ formsemestre_id": "SEM12345", "coefficient": 2, "rang": { "value": "2" - }, - "code": "M1102", - "code_apogee": "VRT1102", - "numero": 1102, - "note": { - "moy": "12.58", - "nb_notes": 50, - "nb_missing": 1, - "max": "16.79", - "min": "02.50", - "nb_valid_evals": 2, - "value": "16.50" - }, - "abbrev": "Initiation \u00e0 la t\u00e9l\u00e9phonie", - "effectif": { - "value": 51 - }, - "titre": "Initiation \u00e0 la t\u00e9l\u00e9phonie d'entreprise", - "evaluation": [ - - ], - "id": "27437" - }, - { - "coefficient": 1.5, - "rang": { - "value": "1" - }, - "code": "M1103", - "code_apogee": "VRT1103", - "numero": 1103, - "note": { - "moy": "08.26", - "nb_notes": 51, - "nb_missing": 0, - "max": "13.41", - "min": "00.94", - "nb_valid_evals": 2, - "value": "13.41" - }, - "abbrev": "Architecture des \u00e9quipements informatiques", - "effectif": { - "value": 51 - }, - "titre": "Architecture des \u00e9quipements informatiques", - "evaluation": [ - - ], - "id": "27451" - }, - { - "coefficient": 2, - "rang": { - "value": "1" - }, - "code": "M1104", - "code_apogee": "VRT1104", - "numero": 1104, - "note": { - "moy": "10.77", - "nb_notes": 51, - "nb_missing": 0, - "max": "17.90", - "min": "04.63", - "nb_valid_evals": 3, - "value": "17.90" - }, - "abbrev": "Principe et architecture des r\u00e9seaux", - "effectif": { - "value": 51 - }, - "titre": "Principe et architecture des r\u00e9seaux", - "evaluation": [ - - ], - "id": "27431" - }, - { - "coefficient": 2, - "rang": { - "value": "1" - }, - "code": "M1105", - "code_apogee": "VRT1105", - "numero": 1105, - "note": { - "moy": "11.00", - "nb_notes": 51, - "nb_missing": 0, - "max": "17.83", - "min": "04.98", - "nb_valid_evals": 2, - "value": "17.83" - }, - "abbrev": "Bases des syst\u00e8mes d'exploitation", - "effectif": { - "value": 51 - }, - "titre": "Bases des syst\u00e8mes d'exploitation", - "evaluation": [ - - ], - "id": "27433" - }, - { - "coefficient": 1.5, - "rang": { - "value": "6" - }, - "code": "M1106", - "code_apogee": "VRT1106", - "numero": 1106, - "note": { - "moy": "13.05", - "nb_notes": 51, - "nb_missing": 0, - "max": "17.79", - "min": "07.08", - "nb_valid_evals": 1, - "value": "16.25" - }, - "abbrev": "Initiation au d\u00e9veloppement Web", - "effectif": { - "value": 51 - }, - "titre": "Initiation au d\u00e9veloppement Web", - "evaluation": [ - - ], - "id": "27449" - }, - { - "coefficient": 1.5, - "rang": { - "value": "9" - }, - "code": "M1107", - "code_apogee": "VRT1107", - "numero": 1107, - "note": { - "moy": "09.36", - "nb_notes": 51, - "nb_missing": 0, - "max": "14.21", - "min": "04.17", - "nb_valid_evals": 3, - "value": "11.66" - }, - "abbrev": "Initiation \u00e0 la mesure du signal", - "effectif": { - "value": 51 - }, - "titre": "Initiation \u00e0 la mesure du signal", - "evaluation": [ - - ], - "id": "27440" - }, - { - "coefficient": 1.5, - "rang": { - "value": "7" - }, - "code": "M1108", - "code_apogee": "VRT1108", - "numero": 1108, - "note": { - "moy": "10.49", - "nb_notes": 51, - "nb_missing": 0, - "max": "16.31", - "min": "05.39", - "nb_valid_evals": 4, - "value": "13.22" - }, - "abbrev": "Acquisition et codage de l'information", - "effectif": { - "value": 51 - }, - "titre": "Acquisition et codage de l'information", - "evaluation": [ - - ], - "id": "27453" - }, - { - "coefficient": 1, - "rang": { - "value": "4 ex" - }, - "code": "1109", - "code_apogee": "VRT1109", - "numero": 1109, - "note": { - "moy": "12.46", - "nb_notes": 51, - "nb_missing": 0, - "max": "16.00", - "min": "09.00", - "nb_valid_evals": 1, - "value": "15.00" - }, - "abbrev": "PT : Recherche documentaire", - "effectif": { - "value": 51 - }, - "titre": "PT : Recherche documentaire", - "evaluation": [ - - ], - "id": "27444" - } - ], - "effectif": "51", - "titre": "D\u00e9couverte m\u00e9tiers", - "id": "UE21456" - }, - { - "acronyme": "UE12", - "rang": "5", - "code_apogee": "VRTU12", - "ects": "14", - "numero": "12", - "note": { - "max": "15.20", - "value": "14.63", - "min": "07.94" - }, - "module": [ - { - "coefficient": 2, - "rang": { - "value": "3 ex" - }, - "code": "M1201", - "code_apogee": "VRT1201", - "numero": 10, - "note": { - "moy": "13.02", - "nb_notes": 51, - "nb_missing": 0, - "max": "16.00", - "min": "10.00", - "nb_valid_evals": 1, - "value": "14.00" - }, - "abbrev": "Anglais", - "effectif": { - "value": 51 - }, - "titre": "Anglais g\u00e9n\u00e9ral de communication et initiation au vocabulaire technique", - "evaluation": [ - - ], - "id": "27430" - }, - { - "coefficient": 2, - "rang": { - "value": "16 ex" - }, - "code": "M1202", - "code_apogee": "VRT1202", - "numero": 20, - "note": { - "moy": "12.74", - "nb_notes": 51, - "nb_missing": 0, - "max": "17.75", - "min": "04.00", - "nb_valid_evals": 2, - "value": "14.00" - }, - "abbrev": "Expression", - "effectif": { - "value": 51 - }, - "titre": "EC: \u00c9l\u00e9ments fondamentaux de la communication", - "evaluation": [ - - ], - "id": "27439" - }, - { - "coefficient": 1, - "rang": { - "value": "1 ex" - }, - "code": "M1203", - "code_apogee": "VRT1203", - "numero": 30, - "note": { - "moy": "NA", - "nb_notes": 0, - "nb_missing": 51, - "max": "-", - "min": "-", - "nb_valid_evals": 0, - "value": "-" - }, - "abbrev": "PPP: Connaitre son champ d'activit\u00e9", - "effectif": { - "value": 51 - }, - "titre": "PPP: Connaitre son champ d'activit\u00e9", - "evaluation": [ - - ], - "id": "27436" - }, - { - "coefficient": 2, - "rang": { - "value": "6" - }, - "code": "M1204", - "code_apogee": "VRT1204", - "numero": 40, - "note": { - "moy": "10.66", - "nb_notes": 51, - "nb_missing": 0, - "max": "16.35", - "min": "05.73", - "nb_valid_evals": 8, - "value": "14.09" - }, - "abbrev": "Mise \u00e0 niveau en num\u00e9ration et calculs", - "effectif": { - "value": 51 - }, - "titre": "Mise \u00e0 niveau en num\u00e9ration et calculs", - "evaluation": [ - - ], - "id": "27454" - }, - { - "coefficient": 2, - "rang": { - "value": "23" - }, - "code": "M1205", - "code_apogee": "VRT1205", - "numero": 50, - "note": { - "moy": "10.37", - "nb_notes": 51, - "nb_missing": 0, - "max": "18.69", - "min": "05.01", - "nb_valid_evals": 5, - "value": "10.58" - }, - "abbrev": "Connaissances et Outils pour le signal", - "effectif": { - "value": 51 - }, - "titre": "Harmonisation des connaissances et des outils pour le signal", - "evaluation": [ - - ], - "id": "27432" - }, - { - "coefficient": 2, - "rang": { - "value": "3 ex" - }, - "code": "M1206", - "code_apogee": "VRT1206", - "numero": 60, - "note": { - "moy": "11.22", - "nb_notes": 51, - "nb_missing": 0, - "max": "16.76", - "min": "03.91", - "nb_valid_evals": 6, - "value": "15.12" - }, - "abbrev": "Circuits \u00e9lectroniques : mise \u00e0 niveau", - "effectif": { - "value": 51 - }, - "titre": "Circuits \u00e9lectroniques : mise \u00e0 niveau", - "evaluation": [ - - ], - "id": "27435" - }, - { - "coefficient": 2, - "rang": { - "value": "1 ex" - }, - "code": "M1207", - "code_apogee": "VRT1207", - "numero": 70, - "note": { - "moy": "08.39", - "nb_notes": 51, - "nb_missing": 0, - "max": "20.00", - "min": "00.00", - "nb_valid_evals": 1, - "value": "20.00" - }, - "abbrev": "Programmation 1", - "effectif": { - "value": 51 - }, - "titre": "Bases de la programmation", - "evaluation": [ - - ], - "id": "27445" - }, - { - "coefficient": 1, - "rang": { - "value": "1 ex" - }, - "code": "M1208", - "code_apogee": "VRT1208", - "numero": 80, - "note": { - "moy": "NA", - "nb_notes": 0, - "nb_missing": 51, - "max": "-", - "min": "-", - "nb_valid_evals": 0, - "value": "-" - }, - "abbrev": "M\u00e9thodologie Universitaire 1", - "effectif": { - "value": 51 - }, - "titre": "Adaptation et m\u00e9thodologie pour la r\u00e9ussite Universitaire", - "evaluation": [ - - ], - "id": "27434" - } ], "effectif": "51", "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques", "id": "UE21478" }, + ... + { "acronyme": "UE 1S", "rang": "1 ex", @@ -1098,7 +345,6 @@ formsemestre_id": "SEM12345", "min": "00.00" }, "module": [ - ], "effectif": "51", "titre": "Sport & Culture", @@ -1109,6 +355,329 @@ 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_) + * **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` + * **Résultat:** Liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. + +``` +{ + "etudid" : 1234, + "formsemestre_id" : 5678, + "groupes" : [ + { + "numero": 1, // Ordre d'affichage dans Scodoc + "partition_id": 62028, + "partition_name": "TD", + "group_id" : 1899, + "group_name": "TD 1" + },{ + "numero": 2, + "partition_id": 62029, + "partition_name": "TP", + "group_id" : 1905, + "group_name": "TP 2" + } + ] +} +``` + + + +## Programmes de formations + * **`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` + * **Résultat:** Liste des formations. + * **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]` + * TODO: détailler le contenu publié + + + + * **`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` + * **Résultat:** La formation, avec UE, matières, modules (_un arbre_). + * **Exemple de résultat:** +``` + { + "nom": "formation", + "UE": "ue", + "matieres": [ + "matiere_1": "maths", + "matiere_2": "anglais", + ... + ], + "modules": ... + } +``` + +## UE + * **`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` + * **Résultat:** Liste des UEs, ressources et SAE d'un semestre + + + + +## Semestres de formation +Les sessions de formation (dénommées "semestres" même si elles durent une année ou un mois) sont représentées par les `formsemestre`. + + * **`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` + * **Résultat:** Informations sur le(s) formsemestre(s). + * **Exemple de résultat:** +``` +[ + { + "annee_scolaire": "2022 - 2023", + "date_debut": "2022-09-01", + "date_fin": "2023-02-02", + "modalite": "FI", + "periode": 1, + "semestre_idx_txt": "S3", + "semestre_idx" : 3, + "session_id" : "GEII-BUT-FI-S3-2022", + "titre_annee": "BUT Génie Electrique et Informatique Industrielle semestre 3 FI 2021-2022" + "titre_num": "BUT Génie Electrique et Informatique Industrielle semestre 3", + "titre": "BUT Génie Electrique et Informatique Industrielle", + "parcours_type": XXX type de parcours + 'formation_id": 87, + } +] +``` + +### Note sur les identifiants de sessions +Le `session_id` peut être utilisé pour identifier de façon prévisible et +(presque) unique une session dans un établissement, ce qui est utile +notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois +du temps ou de services d'enseignement). Cet identifiant est constitué des +informations suivantes: + + * **Département** (RT, GEII, INFO...) (= paramètre `DeptName`, en majuscules) + * **Nom parcours:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME) + * **Modalité:** FI, FC, FA + * **"Spécialité":** S1 (ou S1D pour les semestres décalés), ou le + `code_specialite` si pas de semestres. Le code spécialité est un champ + (libre) nouveau dans la "formation" (programme pédagogique). + * **Année:** année de début de l'année scolaire correspondante (2014 pour + 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) + + +## Modules de formation +Les moduleimpl sont les modules d'un semestre, ou les ressources, ou les SAÉs. +On peut récupérer soit un module par son id, soit la listes des modules d'un semestre. + + * **`moduleimpl`** + * **Méthode:** GET + * **Paramètres**: `formsemestre_id` ou `moduleimpl_id` + * **Routes:** `/api/formations/moduleimpl/` **ou** `/api/formations/moduleimpl//formsemestre/` + * **Résultat:** liste de moduleimpl + * **Exemple de résultat:** + TODO + + + + + +## Groupes et partitions + +L'ensemble des étudiants d'un semestre peut être réparti selon une ou +plusieurs partitions (types de groupes). Chaque partition est constituée +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` + * **Résultat:** La liste de toutes les partitions d'un formsemestre. + * **Exemple de résultat:** +``` +[ + { + "formsemestre_id":"12781", + "partition_id":"23840", + "partition_name":"TD""group":[ + { + "formsemestre_id":"12781", + "partition_id":"23840", + "group_name":"A", + "group_id":"23841", + "partition_name":"TD" + }, + { + "formsemestre_id":"12781", + "partition_id":"23840", + "group_name":"B", + "group_id":"23843", + "partition_name":"TD" + } + ] + }, + { + "formsemestre_id":"12781", + "partition_id":"23941", + "partition_name":"TP""group":[ + { + "..." + }, + "..." + ] + }, + { + "formsemestre_id":"12781", + "partition_id":"22833", + "partition_name":null"group":[ + { + "formsemestre_id":"12781", + "partition_id":"22833", + "group_name":null, + "group_id":"G22834", + "partition_name":null + } + ] + } +] +``` + + + * **`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` + * **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 JSON:** +``` +[ + { + "etat":"I", + "emailperso":null, + "prenom":"Dalil", + "nom_disp":"CLINTO", + "email":"xxx@example.com", + "62029":"A", + "62032":null, + "62031":"G1", + "62030":"A1" + }, + { + "etat":"I", + "emailperso":null, + "prenom":"Georges", + "nom_disp":"BUSH", + "email":"bush@example.com", + "62029":"A", + "62032":null, + "62031":"G1", + "62030":"A1" + }, + ... +] +``` + + + * **`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` + * **Résultat:** Set les groups. + + TODO: à changer, passer les paramètres dans le corps de la requête + + +## Bulletins de notes + * **`evaluations`** + * **Méthode:** GET + * **Paramètres:** `moduleimpl_id` + * **Routes:** `/api/evaluations/` + * **Exemple d'utilisation:** `/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, ...]` + + + * **`evaluation_notes`** + * **Méthode**: GET + * **Paramètres**: `evaluation_id` + * **Routes:** `/api/evaluations/eval_notes/` + * **Exemple d'utilisation:** `/api/evaluations/eval_notes/24` + * **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée. + * **Exemple de résultat:** +``` +[ + { + "84": "13", + "85": "15", + "86": "9", + ... + } +] +``` + + + * **`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` + * **Résultat:** Set les notes d'une évaluation pour un étudiant donné. + TODO vérifier et passer les valeurs dans le corps. + + ## Absences **Remarques**, les dates sont au format iso `yyyy-mm-dd`. Les dates de fin ne sont pas incluses. Et `demi_journee`= 2 si journée complète, =1 si uniquement le matin, =0 si uniquement l'après-midi. @@ -1122,16 +691,14 @@ formsemestre_id": "SEM12345", * **Exemple de résultat:** ```{jour: "2021-02-10", ampm: "0", description: "M2202", }``` (_**ampm** vaut 1 le matin et 0 l'après-midi_). - - + * **`abs_signale`** * **Méthode:** POST * **Paramètres:** `date_debut`, `date_fin`, `module_impl_id=None`, `demi_journee=2`, `estjust=False`, `description`, `etudid` * **Body de la requête:** `date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&description=description&etudid=` * **Exemple d'utilisation:** `date_debut=2015-02-01&date_fin=2015-02-03&demi_journee=4&description=""&etudid=874` * **Résultat:** *html* - - + * **`abs_annule`** * **Méthode:** POST @@ -1148,13 +715,12 @@ formsemestre_id": "SEM12345", * **Exemple d'utilisation:** `context=malade&date_debut=2020-01-05&date_fin=2020-01-06&demi_journee=1` * **Résultat:** *html* - - + * **`abs_groupe_etat`** * **Méthode:** GET * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html` - * **Routes:** `/api/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin` - * **Exemple d'utilisation:** `/api/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30` + * **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` * **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates. * **Exemple de résultat:** si `format="json"` cela donne: ``` @@ -1182,17 +748,15 @@ formsemestre_id": "SEM12345", * **Résultat :** Liste des logos définis pour le site scodoc. * **Exemple de résultat:** `['header', 'footer', 'custom']` - - - * **'récupération d'un logo global'** + + * **`récupération d'un logo global`** * **Méthode:** GET * **Paramètres :** Aucun - * **Route: `/api/logos/` + * **Route:** `/api/logos/` * **Exemple d'utilisation :** `/api/logos/header` * **Résultat :** l'image (format png ou jpg) - - + * **`logo d'un département`** * **Méthode:** GET * **Paramètres:** `format` (json, xml) @@ -1201,21 +765,15 @@ formsemestre_id": "SEM12345", * **Résultat :** Liste des logos définis pour le département visé. * **Exemple de résultat:** `['footer', 'signature', 'universite']` - - - * **'récupération d'un logo global'** + + * **`récupération d'un logo global`** * **Méthode:** GET * **Paramètres :** Aucun - * **Route: `/api/departements//logos/` + * **Route:** `/api/departements//logos/` * **Exemple d'utilisation:** `/api/departements/MMI/logos/header` * **Résultat :** l'image (format png ou jpg) ## En savoir plus -Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. - - - - - +Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. \ No newline at end of file -- 2.45.2 From a9f12ab0dfdb5b8445933ecfc6c0ec48c0312b0b Mon Sep 17 00:00:00 2001 From: Jean-Marie PLACE Date: Wed, 29 Dec 2021 22:26:36 +0100 Subject: [PATCH 2/2] =?UTF-8?q?compl=C3=A9ment=20=C3=A0=20la=20doc:=20pull?= =?UTF-8?q?=20request?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/GuideDeveloppeurs.md | 184 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index 673bce593..bd0f6d7d2 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -119,6 +119,190 @@ Note pour travailler sur VirtualBox: addgroup scodoc vboxsf +#### Préparation d'un PR + +##### Principes généraux + +L'essentiel des remarques/procédures de cette section vise à obtenir une relecture facile des modifications: + +* Eviter les modifications de forme sans substance sémantique. L'utilisation de blackify permet de normaliser la présentation du code + +* Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour les PR courantes (peu volumineuses) + +* La PR doit toujours être énoncé par rapport au dernier commit de la branche master officielle + +##### Manipulations + +Les manipulations sont décrites selons 4 phases du développement: l'installation, la mise en place, le suivi, la livraison. + +###### l'installation +Il est pratique d'avoir en ligne les deux dépot git distant que vous pouvez utiliser: votre dépot personnel (`https://scodoc.org/git//.git`) +et le dépot officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`) + +pour ajouter une référence (et lui donner un nom) vers un depot distant, envoyez la commande: + +```git remote add nom_remote https://scodoc.org/git/ScoDoc/.git``` + +Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`) et une référence vers le depot officiel (`officiel`). L'un des deux +si vous avez iniitalement cloné l'un des deux dépots, la référence vers celui-ci existe et a pour nom òrigin` + +la commande vous exposant tous les dépots connus est : + +`git remote -v` + +##### Mise en place + +l'objectf de ce paragraphe est de créer une branche locale basée sur le master du dépot officiel et bien sur de lui donner un nom. + +pour cela (attention cela va ecraser les éventuels fichiers modifiés) + +``` +git reset --hard officiel/master +git checkout -b ma_modif +``` +A partir de la vous pouvez modifier, tester, developper, commit + +##### Suivi + +Si votre développement prend plusieurs jours, il est probable que la branche principale évolue pendant ce temps. + +Pour garder la cohérence, il est nécessaire de réintégrer en local les modifications de la branche principale. Ceci peut se faire de deux façons. + +une fusion (merge) applique toutes les modifs en une seul commit). c est la méthode courament utilisée + +un rebase rejoue tous les commits de la nouvelle branche par dessus l'état le plus à jour de la branche principal (il en résulte un historique plus linéaire) + +les commandes git correspondantes: + +``` +git fetch officiel +git merge officiel/master +``` +ou +``` +git fetch officiel +git rebase officiel/merge +``` + +##### La livraison + +Ca y est. vous avez terminé le développment. IL n'y a plus qu'à demander l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sur toujours sur la branche locale `ma_modif`) + +###### Etape 1 : faire l'inventaire des fichiers impliqués + +``` +git fetch officiel/master +git diff --name-only officiel/master +``` +###### Etape 2 : passer black sur les fichiers modifiés + +Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé l'équivallent sous pyCharm) + +à défaut les lignes suivantes réalisent le même travail + +``` +for fn in $(git diff --name-only officiel/master) +do + python3 -m black $fn +done +``` +faire une première lecture rapide pour vérifier qu'il n'y ait pas de fichiers modifiés accidentellement. + +pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par exemple) +``` +git diff officiel/master app/fichier.py +``` + +Utilisateurs Windows: +Vérifiez bien que les réglages de fin de ligne suivant bien les règles linux (pas de CR ou \r en fin de ligne juste les LF \n). +Le cas écéheant réglez votre IDE pour cela + +A ce niveau là vous n'avez dans votre branche locales que les différences nécessaires à votre correctif. + +###### Etape 3: résumez tous les commits depuis le point de divergence en un seul commit + +Repérez le point de divergence de votre branche locale avec officiel/master +(normalement git merge-base ma_branche officiel/master) + +demander un rebase interactif depuis ce point + +``` +git rebase -i $(git merge-base HEAD officiel/master) +``` + +vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le début du développment sou scette forme (c'est un exemple le nombre de lignes peut varier) + +``` +pick eb8cbec modif 1 +pick 83eb79e modif 2 + +# Rebase 5ffd074..83eb79e onto 5ffd074 (2 commands) +# +# Commands: +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup [-C | -c] = like "squash" but keep only the previous +# commit's log message, unless -C is used, in which case +# keep only this commit's message; -c is same as -C but +# opens the editor +# x, exec = run command (the rest of the line) using shell +# b, break = stop here (continue rebase later with 'git rebase --continue') +# d, drop = remove commit +# l, label