From de3ee056ab2d62380b53731e4fd27b36ced62eb5 Mon Sep 17 00:00:00 2001 From: leonard_montalbano Date: Mon, 15 Nov 2021 16:14:16 +0100 Subject: [PATCH] petit ajustement a droite a gauche de la doc api scodoc 9 --- docs/ScoDoc9API.md | 141 ++++++++++++++------------------------------- 1 file changed, 42 insertions(+), 99 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 432b42b..b1ac87b 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -42,7 +42,7 @@ Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès. - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/`) - `groups_view` -les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est +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. @@ -51,7 +51,7 @@ Note: # Résumé des fonctions d'API ScoDoc 9 (work in progress) -Basé sur le ticket +Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149) ## Définition des points d'accès à l'API REST (jwt): **Note: à reformatter: le tableau n'est pas lisible et exploitable** @@ -60,23 +60,24 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio | Fonction | Méthode | Paramètres | Exemple | Exemple resultat | Commentaires | |:--------:|:-------:|:----------:|:-------:|:----------------|:------------:| -|etud_dept |GET|code_nip|/api/etud_dept/123|[ {exist: true, dept: "GEII", id: 987, dept_id: 3} ]|liste des étudiants avec le code NIP donné triée par ordre d'inscription décroissant| -|etud_info |GET|etud_id|/api/etud_info/987|{"nom": "Mutis","sexe": "M.","email": "alvaro.mutis@example.com","prenom": "ALVARO","nomprenom": "M. Alvaro MUTIS","insemestre": [{"etat": "I",form_sem_id": "SEM12781","date_fin": "2010-07-30","date_debut": "2010-01-25"},{"etat": "I",form_sem_id": "SEM8396","date_fin": "2009-01-16","date_debut": "2008-09-01"}],"etud_id": "EID8768","domicile": "2 Rue Madame","villedomicile": "Paris","telephonemobile": ""}| | -|etud_bul|GET|etud_id, sem_id|/api/etud_bul/987/12| |cf formsemestre_bulletinetud de [l'ancienne API](https://scodoc.org/ScoDocAPI/)| -|sem_info|GET|sem_id|/api/sem_info/12|[ {"titre": "DUT Génie Electrique et Informatique Industrielle","date_debut": "01/09/2021","date_fin": "02/02/2022","modalite": "FI","sem_id_txt": "S3","titre_num": "DUT Génie Electrique et Informatique Industrielle semestre 3","anneescolaire": "2021 - 2022","periode": 1,"titreannee": "DUT Génie Electrique et Informatique Industrielle semestre 3 FI 2021-2022"} ]| | -|photo|GET|etud_id|/api/photo/123 **OU** /api/photo/123/smal| | | -|formations|GET|dept (*facultatif*)|/api/formations **OU** /api/formations?dept=GEI| { "id": 1,"dept_id": 1,"acronyme": "BUT GEII", "titre": "BUT G\u00e9nie Electrique et Informatique Industrielle", "titre_officiel": "BUT G\u00e9nie Electrique et Informatique Industrielle","version": 1,"formation_code": "FCOD1","type_parcours": 600,"code_specialite": "","form_id": 1 }| | -|form_sem|GET|form_id|/api/formations/form_id| | | -|form_sem_partition|GET|semestre_id|/api/form_sem_partition/semestre_id| | | -|module_list|GET|semestre_id|/api/module_list/semestre_id| | | -|eval_list|GET|module_id|/api/eval_list/module_id| | | -|evaluation_listenotes|GET|eval_id|/api/evalutation_listenotes/eval_id| | | |setGroups|POST|partition_id, groupsLists, groupsToDelete, groupsToCreate|/api/setGroups/???| | | |setNote|POST|eval_id, etud_id, note|/api/setNote/???| | # XXX à revoir XXX Fonctions d'accès aux données + +## Départements + * **`departements`** + * Méthode: GET + * Paramètres: `viewable` (optionnel, si faux liste aussi les départements non accessible à l'utilisateur courant), `format` (json, xml) + * Format URL: + * Exemple d'utilisation: + * Résultat: Liste des id de départements. + * Exemple de résultat: + * Codes HTTP: [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200), [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403), [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) + + ## Etudiants * **`etud_dept`** * Méthode: GET @@ -95,13 +96,13 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio } ] ``` - * Codes HTTP: + * Codes HTTP: [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200), [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403), [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) * **`etud_info`** * Méthode: GET * Paramètres: `etud_id` - * Format URL: `/api/etud_dept/` + * Format URL: `/api/etud_info/` * Exemple d'utilisation: `/api/etud_info/987` * Résultat: Un dictionnaire avec les informations de l'étudiant correspondant à l'id passé en paramètres. * Exemple de résultat: @@ -116,14 +117,14 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio { "etat": "I", form_sem_id": "SEM12781", - "date_fin": "2010-07-30", - "date_debut": "2010-01-25" + "date_fin": "30-07-2010", + "date_debut": "25-01-2010" }, { "etat": "I", form_sem_id": "SEM8396", - "date_fin": "2009-01-16", - "date_debut": "2008-09-01" + "date_fin": "16-01-2009", + "date_debut": "01-09-2008" } ], "etud_id": "EID8768", @@ -132,7 +133,7 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio "telephonemobile": "" } ``` - * Codes HTTP: + * Codes HTTP: [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200), [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403), [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) * **`etud_bul`** @@ -140,9 +141,9 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio * Paramètres: `etud_id`, `sem_id` * Format URL: `/api/etud_bul//` * Exemple d'utilisation: `/api/etud_bul/987/12` - * Résultat: - * Exemple de résultat: - * Codes HTTP: + * 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) + * Codes HTTP: [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200), [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403), [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) * **`etud_photo`** @@ -150,9 +151,9 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio * Paramètres: `etud_id`, `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_) - * Résultat: - * Exemple de résultat: - * Codes HTTP: + * Résultat: Image en JPEG ou PNG. + * Exemple de résultat: + * Codes HTTP: [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200), [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403), [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) ## Semestres @@ -178,20 +179,10 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio } ] ``` - * Codes HTTP: + * Codes HTTP: [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200), [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403), [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) - -## Départements - * **`departements`** - * Méthode: - * Paramètres: `viewable` (optionnel, si faux liste aussi les départements non accessible à l'utilisateur courant), `format` (json, xml) - * Format URL: - * Exemple d'utilisation: - * Résultat: Liste des id de départements. - * Exemple de résultat: - * Codes HTTP: - + ## Programmes de formations * **`formations`** @@ -205,7 +196,7 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio * **`form_export`** - * Méthode: + * Méthode: GET * Paramètres: `form_id`, `export_ids` (défaut "faux") * Format URL: * Exemple d'utilisation: @@ -225,7 +216,17 @@ Les sessions de formation (dénommées "semestres" même si elles durent une ann * Exemple de résultat: * Codes HTTP: -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: +## Modules de formation + * **`Notes/do_moduleimpl_list`** + * Paramètres: `form_sem_id, moduleimpl_id, module_id]` + * Résultat: liste de moduleimpl + + * **`Notes/do_moduleimpl_withmodule_list`** + * Paramètres: `form_sem_id, moduleimpl_id, module_id]` + * Résultat: liste triée de moduleimpl, avec l'attribut `module` + +## 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: * Département (RT, GEII, INFO...) (= paramètre `DeptName`, en majuscules) * Nom parcours: DUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME) @@ -375,56 +376,6 @@ Et un autre exemple en format JSON: * Codes HTTP: -## Etudiants - * **`etud_info`** - * Paramètres: `etud_id` ou `code_nip` ou `code_ine` - * Résultat: informations sur cette étudiant et les semestres dans lesquels il est (ou a été) inscrit. - * Exemple: `etud_info?format=json&etud_id=12345` -``` -{ - "nom": "Mutis", - "sexe": "M.", - "email": "alvaro.mutis@example.com", - "prenom": "ALVARO", - "nomprenom": "M. Alvaro MUTIS", - "insemestre": [ - { - "etat": "I", - form_sem_id": "SEM12781", - "date_fin": "2010-07-30", - "date_debut": "2010-01-25" - }, - { - "etat": "I", - form_sem_id": "SEM8396", - "date_fin": "2009-01-16", - "date_debut": "2008-09-01" - } - ], - "code_ine": "", - "etud_id": "EID8768", - "code_nip": "10991002", - "photo_url": "/ScoDoc/static/photos/F13/RT_EID8768.h90.jpg", - - "domicile": "2 Rue Madame", - "villedomicile": "Paris", - "telephonemobile": "" - "fax": "", - - "annee_bac": "2010", - "bac": "S", - "specialite": "SCIENTIFIQUE", - - "nomlycee": "", - "villelycee": "", - "codelycee": "0950650R", - "codepostallycee": "", - -} -``` - - - ## Bulletins de notes * **`evaluations`** * Méthode: GET @@ -1125,15 +1076,7 @@ Et un autre exemple en format JSON: ... ]``` * Remarque: on peut spécifier plusieurs groupes. - -## Modules - * **`Notes/do_moduleimpl_list`** - * Paramètres: `form_sem_id, moduleimpl_id, module_id]` - * Résultat: liste de moduleimpl - - * **`Notes/do_moduleimpl_withmodule_list`** - * Paramètres: `form_sem_id, moduleimpl_id, module_id]` - * Résultat: liste triée de moduleimpl, avec l'attribut `module` + ## En savoir plus