From 49bcfcee1c4a33b2f704125ee23683ef1443f609 Mon Sep 17 00:00:00 2001 From: leonard_montalbano Date: Tue, 26 Apr 2022 17:07:20 +0200 Subject: [PATCH] =?UTF-8?q?mise=20=C3=A0=20jour=20de=20la=20documentation?= =?UTF-8?q?=20api=20scodoc9=20pour=20la=20partie=20departement=20et=20etud?= =?UTF-8?q?iant?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ScoDoc9API.md | 504 +++++++++++++++++---------------------------- 1 file changed, 188 insertions(+), 316 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 787654b..2e7daaa 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -1,5 +1,5 @@ -# API pour ScoDoc 9 +## API pour ScoDoc 9 L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON. La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification. @@ -24,47 +24,51 @@ Les objets ScoDoc manipulables sont identifiés par des id. L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`. -# Fonctions de l'API ScoDoc 7 portées en ScoDoc 9 +## Configuration de ScoDoc pour utiliser l'API -L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md) +Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats. -Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les -fonctions suivantes sont disponibles avec le mécanisme d'authentification -basique de ScoDoc 7. Elles sont considérées comme *obsolètes* ("deprecated") et -disparaitront en juillet 2022. +En général, il est recommandé de créer un rôle, de lui attribuer les permissions +que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle. -Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès. +En ligne de commande, cela peut se faire comme suit (voir détail des commandes +[sur le guide de configuration](GuideConfig.md)). - - `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/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) - - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/`) - - `groups_view` (deviendra `groups`) +``` +# se connecter comme utilisateur scodoc +su - scodoc -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. +# Créer un rôle +flask create-role LecteurAPI +# Lui donner les droits nécessaires: ici APIView +flask edit-role LecteurAPI -a APIView -Note: - - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API. +# Créer un nouvel utilisateur avec ce rôle: +flask user-create lecteur_api LecteurAPI @all -# Fonctions d'API ScoDoc 9 (work in progress) +# Ou bien, si on veut utiliser un compte existant: +# associer notre rôle à un utilisateur +flask user-role lecteur_api -a LecteurAPI + + +# Au besoin, changer le mot de passe de l'utilisateur +# (on aura besoin de ce mot de passe dans la configuration du client d'API) +flask user-password lecteur_api +... +``` + +## Fonctions d'API ScoDoc 9 (work in progress) Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149) -La documentation ci-dessous concerne la **future** version De ScoDoc. +La documentation ci-dessous concerne la **future** version de ScoDoc (9.3, avec +parties expérimentales progressivement mises en production à partir de 9.2.12). -## Accès à l'API REST +### Accès à l'API REST 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 +#### Authentification Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant @@ -89,7 +93,7 @@ La réponse doit ressembler à ceci: Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple complet en python d'interrogation de l'API. -### Codes HTTP +#### 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. @@ -107,315 +111,156 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * [503](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/503) : L'API est momentanément indisponible, réessayez dans quelques minutes. -## Départements +### Départements * **`departements`** * **Méthode:** GET - * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessibles à l'utilisateur courant), `format` (json, xml) - * **Routes:** `/ScoDoc/api/departements` - * **Exemple d'utilisation:** `/ScoDoc/api/departements` + * **Routes:** `/departements` + * **Exemple d'utilisation:** `/api/departements` * **Résultat:** Liste des id de départements. - * **Exemple de résultat:** `[id_1, id_2, id_3, ...]` + * **Exemple de résultat:** `[1, 2, 3, ...]` * **`liste_etudiants`** * **Méthode:** GET * **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. + * **Routes:** `/departements//etudiants/liste` ou `/api/departements//etudiants/liste/` + * **Exemple d'utilisation:** `/api/departements/MMI/etudiants/liste` + * **Résultat:** liste des étudiants d'un département, par défaut, ou d'un semestre si renseigné. (json) - * **`liste_semestres_actifs`** + * **`liste_semestres_courant`** * **Méthode:** GET * **Paramètres:** `dept` - * **Routes:** `/ScoDoc/api/departements//semestres_actifs` - * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/semestres_actifs` + * **Routes:** `/departements//semestres_courants` + * **Exemple d'utilisation:** `/api/departements/MMI/semestres_courants` * **Résultat:** Liste des semestres actifs d'un département donné. (_réponse sous format json_) - * **`referenciel_competences`** + * **`referentiel_competences`** * **Méthode:** GET - * **Paramètres:** `dept`, `formation` (_`formation` étant un id de formation, un programme pédagogique_) - * **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_) + * **Paramètres:** `dept`, `formation_id` + * **Routes:** `/departements//formations//referentiel_competences` + * **Exemple d'utilisation:** `api/departements/MMI/formations/1/referentiel_competences` + * **Résultat:** Le référentiel de compétences d'une formation donnée (json). (_pas toujours présent_) + * XXX obtenir la liste des référentiels -## Etudiants - * **`etud_dept`** + * **`semestre_index`** * **Méthode:** GET - * **Paramètres:** `code_nip` - * **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:** - ``` - [ - { - exist: true, - dept: "GEII", - id: 987, - dept_id: 3 - } - ] - ``` - + * **Paramètres:** `dept`, `formsemestre_id` + * **Routes:** `/departements//formsemestre//programme` + * **Exemple d'utilisation:** `api/departements/MMI/formsemestre/1/programme` + * **Résultat:** Retourne la liste des Ues, ressources et SAE d'un semestre (json). - * **`etudiant`** + +### Etudiants + + * **`etudiants_courant`** * **Méthode:** GET - * **Paramètres:** `etudid` - * **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. + * **Routes:** `/etudiants/courant` + * **Exemple d'utilisation:** `/api/etudiants/courant` + * **Résultat:** Retourne la liste des étudiants courant (json). * **Exemple de résultat:** ``` { - "nom": "Mutis", - "sexe": "M.", - "email": "alvaro.mutis@example.com", - "prenom": "ALVARO", - "nomprenom": "M. Alvaro MUTIS", - "insemestre": [ - { - "etat": "I", - "formsemestre_id": "12781", - "date_fin": "2010-07-30", - "date_debut": "2010-01-25" - "parcours_type": XXX type de parcours, en discussion XXX - }, - { - "etat": "I", - "formsemestre_id": "8396", - "date_fin": "2009-01-16", - "date_debut": "2008-09-01" - } - ], - "etudid": "8768", - "domicile": "2 Rue Madame", - "villedomicile": "Paris", - "telephonemobile": "" - } + { + "civilite": "X", + "code_ine": null, + "code_nip": null, + "date_naissance": null, + "email": null, + "emailperso": null, + "etudid": 18, + "nom": "MOREL", + "prenom": "JACQUES" + }, + { + "civilite": "X", + "code_ine": null, + "code_nip": null, + "date_naissance": null, + "email": null, + "emailperso": null, + "etudid": 19, + "nom": "FOURNIER", + "prenom": "ANNE" + }, + ... + } ``` - + * **`etudiant`** + * **Méthode:** GET + * **Paramètres:** `etudid`, `nip`, `ine` + * **Routes:** `/etudiant/etudid/` ou `/etudiant/nip/` ou `/etudiant/ine/` + * **Exemple d'utilisation:** `/api/etudiant/nip/1` + * **Résultat:** Retourne les informations de l'étudiant correspondant à l'id passé en paramètres. (json) + * **Exemple de résultat:** + ``` + { + "civilite": "X", + "code_ine": null, + "code_nip": null, + "date_naissance": null, + "email": null, + "emailperso": null, + "etudid": 18, + "nom": "MOREL", + "prenom": "JACQUES" + } + ``` + + + * **`etudiant_formsemestres`** + * **Méthode:** GET + * **Paramètres:** `etudid`, `nip`, `ine` + * **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) + + * **`etudiant_bulletin_semestre`** * **Méthode:** GET - * **Paramètres:** `etudid`, `sem_id` - * **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. - - Voir aussi [Bulletins par défaut](https://scodoc.org/ParametrageBulletins/#exemple-1-bulletins-par-defaut) - - - * **`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:** : `/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`) -``` -{ -"rang": { - "ninscrits": 52, - "value": "1" -}, -"etape_apo2": "", -"etape_apo3": "", -"etape_apo4": "", -"etudiant": { - "nom": "BOLANO", - "prenom": "Roberto", - "sexe": "M.", - "code_ine": "", - etudid": "9860", - "code_nip": "123456789", - "email": "roberto@santateresa.mx", - "photo_url": "\/ScoDoc\/static\/photos\/F68\/RT_29960.h90.jpg" -}, -"bonus_sport_culture": { - "value": 0 -}, -"absences": { - "nbabsjust": 0, - "nbabs": 1 -}, -"decision": { - "etat": "I", - "code": "ADM", - "compenseformsemestre_id" : "SEM12345" /* si ce semestre en compense un autre */ -}, -"note": { - "max": "15.51", - "moy": "10.80", - "value": "15.51", - "min": "07.29" -}, - etudid": "9860", -"decision_ue": [ - { - "acronyme": "UE11", - "code": "ADM", - "ects": "16.0", - "titre": "D\u00e9couverte m\u00e9tiers", - "numero": "11", - "ue_id": "UE21456" - }, - { - "acronyme": "UE12", - "code": "ADM", - "ects": "14.0", - "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques", - "numero": "12", - "ue_id": "UE21478" - } -], -"ue_capitalisee": [ - -], -"publie": 1, -"autorisation_inscription": [ - { - "semestre_id": 2 - } -], -"appreciation": [ - -], -"note_max": { - "value": 20 -}, -"date": "2014-07-12T17:38:47.693262", -"rang_group": [ - { - "ninscrits": 26, - "value": "1", - "group_type": "TD", - "group_name": "B" - }, - { - "ninscrits": 13, - "value": "1", - "group_type": "TP", - "group_name": "B1" - }, - ... - -], -formsemestre_id": "SEM12345", -"etape_apo": "V1RT", -"ue": [ - { - "acronyme": "UE11", - "rang": "1", - "code_apogee": "VRTU11", - "ects": "16", - "numero": "11", - "note": { - "max": "16.17", - "value": "16.17", - "min": "06.56" - }, - "module": [ - { - "coefficient": 3, - "rang": { - "value": "1" - }, - "code": "M1101", - "code_apogee": "VRT1101", - "numero": 1101, - "note": { - "moy": "08.94", - "nb_notes": 51, - "nb_missing": 0, - "max": "19.18", - "min": "03.70", - "nb_valid_evals": 3, - "value": "19.18" - }, - "abbrev": "R\u00e9seaux d'entreprises", - "effectif": { - "value": 51 - }, - "titre": "Initiation aux r\u00e9seaux d'entreprises", - "evaluation": [ - ], - "id": "27427" - }, - { - "coefficient": 2, - "rang": { - "value": "2" - ], - "effectif": "51", - "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques", - "id": "UE21478" - }, - ... - - { - "acronyme": "UE 1S", - "rang": "1 ex", - "code_apogee": "", - "ects": "0", - "numero": "13", - "note": { - "max": "00.00", - "value": "00.00", - "min": "00.00" - }, - "module": [ - ], - "effectif": "51", - "titre": "Sport & Culture", - "id": "UE23716" - } -], -"situation": "Inscrit le 2015-09-02. D\u00e9cision jury: Valid\u00e9. UE acquises: UE11, UE12. Autoris\u00e9 \u00e0 s'inscrire en S2." -} -``` - - - - * **`etudiant_photo`** - * **Méthode:** GET - * **Paramètres:** `etudid`, `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. + * **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` + * **Routes:** `/etudiant/etudid//formsemestre//bulletin` ou `/etudiant/nip//formsemestre//bulletin` ou `/etudiant/ine//formsemestre//bulletin` + * **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin` + * **Résultat:** Retourne le bulletin d'un étudiant en fonction de son id et d'un semestre donné. (json) * **`etudiant_groups`** * **Méthode:** GET - * **Paramètres:** `etudid`, `formsemestre_id` - * **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é. - -``` -{ - "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" - } - ] -} -``` + * **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` + * **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:** + ``` + [ + { + "partition_id": 1, + "id": 1, + "formsemestre_id": 1, + "partition_name": "TD", + "numero": 0, + "bul_show_rank": false, + "show_in_lists": true, + "group_id": 1, + "group_name": B + }, + { + "partition_id": 2, + "id": 2, + "formsemestre_id": 1, + "partition_name": "TP", + "numero": 1, + "bul_show_rank": false, + "show_in_lists": true, + "group_id": 2, + "group_name": "A" + }, + ... + ] + ``` @@ -451,7 +296,7 @@ formsemestre_id": "SEM12345", } ``` -## UE +### UE * **`UEs`** * **Méthode:** GET * **Paramètres:** `dept`, `̀semestre` @@ -462,7 +307,7 @@ formsemestre_id": "SEM12345", -## Semestres de formation +### 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`** @@ -492,7 +337,7 @@ Les sessions de formation (dénommées "semestres" même si elles durent une ann ] ``` -### Note sur les identifiants de sessions +#### 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 @@ -513,7 +358,7 @@ informations suivantes: **Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI) -## Modules de formation +### 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. @@ -529,7 +374,7 @@ On peut récupérer soit un module par son id, soit la listes des modules d'un s -## Groupes et partitions +### 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 @@ -663,7 +508,7 @@ d'un nombre quelconque de groupes d'étudiants. TODO: à changer, passer les paramètres dans le corps de la requête -## Bulletins de notes +### Bulletins de notes * **`evaluations`** * **Méthode:** GET * **Paramètres:** `moduleimpl_id` @@ -701,7 +546,7 @@ d'un nombre quelconque de groupes d'étudiants. TODO vérifier et passer les valeurs dans le corps. -## Absences +### 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. @@ -761,7 +606,7 @@ d'un nombre quelconque de groupes d'étudiants. ] ``` -## Logos +### Logos * **`liste des logos globaux`** * **Méthode:** GET @@ -797,6 +642,33 @@ d'un nombre quelconque de groupes d'étudiants. * **Résultat :** l'image (format png ou jpg) +### En savoir plus +Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. -## En savoir plus -Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. \ No newline at end of file +## Fonctions de l'API ScoDoc 7 portées en ScoDoc 9 + +L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md) + +Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les +fonctions suivantes sont disponibles avec le mécanisme d'authentification +basique de ScoDoc 7. Elles sont considérées comme *obsolètes* ("deprecated") et +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/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/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) + - `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 +à dire `https://votre.site.fr/ScoDoc//Scolarite/`, et répondent en GET et +en POST. + +Note: + - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.