From ca7a2fe5460f479dadc511ae7766592e4a101481 Mon Sep 17 00:00:00 2001 From: leonard_montalbano Date: Thu, 18 Nov 2021 17:16:04 +0100 Subject: [PATCH] revision doc api scodoc9 --- docs/ScoDoc9API.md | 149 ++++++++++++++++++++++----------------------- 1 file changed, 73 insertions(+), 76 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 8e183a8..037ddc2 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -36,7 +36,7 @@ Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès. - `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/form_sem` (deviendra `api/formsemestre`) + - `Notes/formsemestre_id` (deviendra `api/formsemestre`) - `Notes/formsemestre_bulletinetud` (deviendra `api/formsemestre_bulletinetud`) - `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/ etudid>`) @@ -77,11 +77,11 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ # Description d'accès aux données ## Départements - * **`departements`** + * **`departement`** * **Méthode:** GET * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessible à l'utilisateur courant), `format` (json, xml) - * **Format URL:** `/api/departements` - * **Exemple d'utilisation:** `/api/departements` + * **Format URL:** `/api/departement` + * **Exemple d'utilisation:** `/api/departement` * **Résultat:** Liste des id de départements. * **Exemple de résultat:** `[id_1, id_2, id_3, ...]` @@ -106,11 +106,11 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ ``` - * **`etud_info`** + * **`etud`** * **Méthode:** GET * **Paramètres:** etudid - * **Format URL:** `/api/etud_info/` - * **Exemple d'utilisation:** `/api/etud_info/987` + * **Format URL:** `/api/etud/` + * **Exemple d'utilisation:** `/api/etud/987` * **Résultat:** Un dictionnaire avec les informations de l'étudiant correspondant à l'id passé en paramètres. * **Exemple de résultat:** ``` @@ -123,15 +123,15 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ "insemestre": [ { "etat": "I", - "form_sem_id": "SEM12781", - "date_fin": "30-07-2010", - "date_debut": "25-01-2010" + "formsemestre_id": "SEM12781", + "date_fin": "2010-07-30", + "date_debut": "2010-01-25" }, { "etat": "I", - "form_sem_id": "SEM8396", - "date_fin": "16-01-2009", - "date_debut": "01-09-2008" + "formsemestre_id": "SEM8396", + "date_fin": "2009-01-16", + "date_debut": "2008-09-01" } ], "etudid": "EID8768", @@ -145,8 +145,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`etud_bul`** * **Méthode:** GET * **Paramètres:** `etudid`, `sem_id` - * **Format URL:** `/api/etud_bul//` - * **Exemple d'utilisation:** `/api/etud_bul/987/12` + * **Format URL:** `/api/etud//bul/` + * **Exemple d'utilisation:** `/api/etud/987/bul/12` * **Résultat:** Le bulletin d'un étudiant en fonction de son id et d'un semestre donné. * **Exemple de résultat:** [Bulletins par défaut](https://scodoc.org/ParametrageBulletins/#exemple-1-bulletins-par-defaut) @@ -155,8 +155,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`etud_photo`** * **Méthode:** GET * **Paramètres:** `etudid`, `small` - * **Format URL:** `/api/etud_photo/` **OU** `/api/etud_photo//small` (_ajout du paramètre **small** pour la version small_) - * **Exemple d'utilisation:** `/api/etud_photo/123` **OU** `/api/etud_photo/123/small` (_pour la version small_) + * **Format URL:** `/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. @@ -165,7 +165,7 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **`sem_info`** * **Méthode:** GET * **Paramètres:** `sem_id` - * **Format URL:** `/api/sem_id/` + * **Format URL:** `/api/sem_info/` * **Exemple d'utilisation:** `/api/sem_info/12` * **Résultat:** Une liste avec les informations du semestre correspondant à l'id passé en paramètres. * **Exemple de résultat:** @@ -173,8 +173,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ [ { "titre": "DUT Génie Electrique et Informatique Industrielle", - "date_debut": "01/09/2021", - "date_fin": "02/02/2022", + "date_debut": "2021-09-01", + "date_fin": "2022-02-02", "modalite": "FI", "sem_id_txt": "S3", "titre_num": "DUT Génie Electrique et Informatique Industrielle semestre 3", @@ -188,21 +188,21 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ ## Programmes de formations - * **`formations`** + * **`formation`** * **Méthode:** GET * **Paramètres:** `form_id` (_optionnel, si absent liste toutes les formations_) - * **Format URL:** `/api/formations` **ou** `/api/formations/` - * **Exemple d'utilisation:** `/api/formations` **ou** `̀/api/formations/1` + * **Format URL:** `/api/formation` **ou** `/api/formation/` + * **Exemple d'utilisation:** `/api/formation` **ou** `̀/api/formation/1` * **Résultat:** Liste des formations. - * **Exemple de résultat:** `[form_1, form_2, form_3, ...]` + * **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]` - * **`form_export`** + * **`formation_export`** * **Méthode:** GET * **Paramètres:** `form_id`, `export_ids` (_par défaut "faux"_) - * **Format URL:** `/api/form_export/` - * **Exemple d'utilisation:** `/api/form_export/596` + * **Format URL:** `/api/formation_export/` + * **Exemple d'utilisation:** `/api/formation_export/596` * **Résultat:** La formation, avec UE, matières, modules (_un arbre_). * **Exemple de résultat:** ``` @@ -217,37 +217,38 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ "modules": "module" } ``` - - -## 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 `form_sem`. - - * **`form_sem`** - * **Méthode:** GET - * **Paramètres (_tous optionnels_):** `form_sem_id`, `form_id`, `etape_apo`, `etape_apo2` - * **Format URL:** `/api/form_sem?form_id=1&etape_apo=V1RT` - * **Exemple d'utilisation:** `/api/form_sem?format=xml&etape_apo=V1RT` - * **Résultat:** Liste des semestres correspondant. - * **Exemple de résultat:** `[sem_1, sem_2, sem_3, ...]` - - + ## UE ... -## '################################################################################' ## Modules de formation * **`Notes/do_moduleimpl_list`** - * **Paramètres**: `form_sem_id, moduleimpl_id, module_id]` + * **Paramètres**: `formsemestre_id, moduleimpl_id, module_id]` * **Résultat:** liste de moduleimpl * **`Notes/do_moduleimpl_withmodule_list`** - * **Paramètres**: `form_sem_id, moduleimpl_id, module_id]` + * **Paramètres**: `formsemestre_id, moduleimpl_id, module_id]` * **Résultat:** liste triée de moduleimpl, avec l'attribut `module` -## '#################################################################################' + +## 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_id`. + + * **`formsemestre_id`** + * **Méthode:** GET + * **Paramètres (_tous optionnels_):** `formsemestre_id`, `form_id`, `etape_apo`, `etape_apo2` + * **Format URL:** `/api/formsemestre_id?form_id=1&etape_apo=V1RT` + * **Exemple d'utilisation:** `/api/formsemestre_id?format=xml&etape_apo=V1RT` + * **Résultat:** Liste des semestres correspondant. + * **Exemple de résultat:** `[sem_1, sem_2, sem_3, ...]` + + + + + ## 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 (eg gestion d'emplois du temps ou de services d'enseignement). Cet identifiant est constitué des informations suivantes: @@ -267,29 +268,29 @@ Le `session_id` peut être utilisé pour identifier de façon prévisible et (pr ## 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. - * **`form_sem_partition`** + * **`formsemestre_id_partition`** * **Méthode: GET** - * **Paramètres:** `form_sem_id` - * **Format URL:** `/api/form_sem_partition/` - * **Exemple d'utilisation:** `/api/form_sem_partition/48` - * **Résultat:** La liste de toutes les partitions celon un `form_sem_id` donné. + * **Paramètres:** `formsemestre_id` + * **Format URL:** `/api/formsemestre_id_partition/` + * **Exemple d'utilisation:** `/api/formsemestre_id_partition/48` + * **Résultat:** La liste de toutes les partitions selon un `formsemestre_id` donné. * **Exemple de résultat:** ici au format JSON ``` [ { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P23840", "partition_name": "TD" "group": [ { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P23840", "group_name": "A", "group_id": "G23841", "partition_name": "TD" }, { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P23840", "group_name": "B", "group_id": "G23843", @@ -298,19 +299,19 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu ], }, { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P23941", "partition_name": "TP" "group": [ { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P23941", "group_name": "A1", "group_id": "G23942", "partition_name": "TP" }, { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P23941", "group_name": "A2", "group_id": "G23943", @@ -319,12 +320,12 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu ], }, { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P22833", "partition_name": null "group": [ { - "form_sem_id": "SEM12781", + "formsemestre_id": "SEM12781", "partition_id": "P22833", "group_name": null, "group_id": "G22834", @@ -338,7 +339,7 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu * **`groups_view`** * **Méthode:** GET - * **Paramètres:** `form_sem_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I` + * **Paramètres:** `formsemestre_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I` * **Format URL:** * **Exemple d'utilisation:** * **Résultat:** Liste des étudiants dans un groupe. @@ -443,7 +444,7 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu * **`Notes/formsemestre_bulletinetud`** * **Méthode:** GET - * **Paramètres:** `form_sem_id`, `etudid`, `format` (`xml`ou `json`), `version` (`short`, `selectedevals` ou `long`) + * **Paramètres:** `formsemestre_id`, `etudid`, `format` (`xml`ou `json`), `version` (`short`, `selectedevals` ou `long`) * **Format URL:** * **Exemple d'utilisation:** * **Résultat:** Un bulletin de notes. @@ -477,7 +478,7 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu "decision": { "etat": "I", "code": "ADM", - "compenseform_sem_id" : "SEM12345" /* si ce semestre en compense un autre */ + "compenseformsemestre_id" : "SEM12345" /* si ce semestre en compense un autre */ }, "note": { "max": "15.51", @@ -558,7 +559,7 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu "group_name": "" } ], - form_sem_id": "SEM12345", + formsemestre_id": "SEM12345", "etape_apo": "V1RT", "ue": [ { @@ -1073,12 +1074,12 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu "id": "UE23716" } ], - "situation": "Inscrit le 02\/09\/2015. D\u00e9cision jury: Valid\u00e9. UE acquises: UE11, UE12. Autoris\u00e9 \u00e0 s'inscrire en S2." + "situation": "Inscrit le 2015-09-02. D\u00e9cision jury: Valid\u00e9. UE acquises: UE11, UE12. Autoris\u00e9 \u00e0 s'inscrire en S2." } ``` ## 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. +**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. * **`absences`** @@ -1095,36 +1096,34 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu * **`abs_signale`** * **Méthode:** POST * **Paramètres:** `date_debut`, `date_fin`, `module_impl_id=None`, `demi_journee=2`, `estjust=False`, `description`, `etudid` - * **Format URL:** `/api/abs_signale/?date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&description=description&etudid=` - * **Exemple d'utilisation:** `/api/abs_signale/?date_debut=2015/02/01&date_fin=2015/02/03&demi_journee=4&description=""&etudid=874` + * **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* - * **Remarques:** Dates au format iso `yyyy/mm/dd`. Date de fin non incluse. `demi_journee`: 2 si journée complète, 1 matin, 0 après-midi. * **`abs_annule`** * **Méthode:** POST * **Paramètres:** `date_debut`, `date_fin`, `demi_journee`, `etudid` - * **Format URL:** `/api/abs_annule/?date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&etudid=` - * **Exemple d'utilisation:** `/api/abs_annule/?date_debut=2004/05/03&date_fin=2004/06/07&demi_journee=2&etudid=451` + * **Body de la requête:** `date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&etudid=` + * **Exemple d'utilisation:** `date_debut=2004-05-03&date_fin=2004-06-07&demi_journee=2&etudid=451` * **Résultat:** *html* - * **Remarques:** Dates au format iso `yyyy/mm/dd`. Date de fin non incluse. `demi_journee`: 2 si journée complète, 1 matin, 0 après-midi. * **`abs_annule_justif`** * **Méthode:** POST * **Paramètres:** `context`, `date_debut`, `date_fin`, `demi_journee` - * **Format URL:** `/api/abs_annule_justif/?context=context&date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee` - * **Exemple d'utilisation:** `/api/abs_annule_justif/?context=malade&date_debut=2020/01/05&date_fin=2020/01/06&demi_journee=1` + * **Body de la requête:** `context=context&date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee` + * **Exemple d'utilisation:** `context=malade&date_debut=2020-01-05&date_fin=2020-01-06&demi_journee=1` * **Résultat:** *html* - * **Remarques:** Dates au format iso `yyyy/mm/dd`. Date de fin non incluse. `demi_journee`: 2 si journée complète, 1 matin, 0 après-midi. + * **`abs_groupe_etat`** * **Méthode:** GET * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html` * **Format URL:** `/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` + * **Exemple d'utilisation:** `/api/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: ``` @@ -1141,8 +1140,6 @@ L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieu ... ] ``` - - * **Remarques:** Dates au format iso `yyyy/mm/dd`. Date de fin non incluse. `demi_journee`: 2 si journée complète, 1 matin, 0 après-midi.