diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 1d14c3c34..f0e1ef6c6 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -175,7 +175,7 @@ par le serveur ScoDoc. ### Carte syntaxique -![carte_syntaxique](img/API_Chart.svg)#### Structure Département +![carte_syntaxique](img/API_Chart.svg) ### Tableau récapitulatif des point de l'API @@ -239,8 +239,9 @@ Ce tableau est trié selon le type des informations retournées | note* | |GET | [evaluation-notes](http://localhost:8000/ScoDoc9API/**`#`**evaluation-notes) | | user | |GET | [user](http://localhost:8000/ScoDoc9API/**`#`**user) | -### **Départements** +### **API Départements** +#### Structure Département | attribut | type | commentaire | |:-----------------|:--------|:---------------------------------------| @@ -274,7 +275,7 @@ Ce tableau est trié selon le type des informations retournées * **Résultat:** Un département * **Exemple de résultat:** [departement.json](samples/sample_departement.json.md) -### **Formation** +### **API Formation** #### Structure Formation | attribut | type | commentaire | |:----------------------------|:------------|:--------------------------------------------------| @@ -317,16 +318,17 @@ Ce tableau est trié selon le type des informations retournées * **Résultat:** Description de la formation. * **Exemple de résultat:** [formation.json](samples/sample_formation.json.md) -### **Formsemestre** +### **API Formsemestre** Les sessions de formation (qu'elles durent une année ou un mois) sont représentées par les `formsemestre`. #### Note sur les identifiants de formsemestre Le `session_id` peut être utilisé pour identifier de façon prévisible et -(presque) unique un formsemestre) dans un établissement, ce qui est utile +(presque) unique un formsemestre 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...) (acronyme en majuscules) * **Nom parcours:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME) * **Modalité:** FI, FC, FA @@ -341,6 +343,43 @@ des informations suivantes: **Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI). +#### Structure Formsemestre + +| attribut | type | commentaire | +|:----------------------------|:------------|:-----------------------------------------------| +| _**id**_ | int | id unique | +| _**formsemestre_id**_ | int | identification unique | +| _**semestre_id**_ | int | rang du semestre 1, ... | +| _**elt_annee_apo**_ | ??? | | +| _**titre**_ | string | | +| _**titre_court**_ | string | | +| _**titre_num**_ | string | | +| _**session_id**_ | string | cf. Note sur les identifiants de formsemestre | +| _**block_moyennes**_ | bool | inhibe le calcul des mmoyennes | +| _**scodoc7_id**_ | int | | +| _**date_debut**_ | date | | +| _**date_fin**_ | date | | +| _**gestion_semestrielles**_ | bool | | +| _**gestion_compensation**_ | bool | | +| _**bul_bgcolor**_ | string | Couleur (CSS) de fond du bulletin | +| _**etat**_ | bool | | +| _**dept_id**_ | int | | +| _**modalite**_ | string | "FI", "FA", ... | +| _**bul_hide_xml**_ | bool | | +| _**resp_can_change_ens**_ | bool | | +| _**resp_can_edit**_ | bool | | +| _**ens_can_edit_eval**_ | bool | | +| _**elt_sem_apo**_ | string | | +| _**parcours**_ | ???? | | +| _**annee_scolaire**_ | int | | +| _**date_debut_iso**_ | string | | +| _**date_fin_iso**_ | string | | +| _**departement**_ | Département | | +| _**etape_apo**_ | string | | +| _**formation_id**_ | int | | +| _**formation**_ | Formation | | +| _**responsables**_ | int* | liste des ids des enseignants responsables | + #### **departement-formsemestres_ids** * **Méthode:** GET * **Paramètres:** `dept` @@ -395,10 +434,23 @@ informatique de 2014 en formation initiale (FI). * **Résultat:** Description du formsemestre. * **[Exemple de résultat:](samples/sample_formsemestre.json.md)** -### **Moduleimpl** +### **API Moduleimpl** + +#### Structure ModuleImpl Le moduleimpl est la mise en place d'un module dans un formsemestre (avec son -responsable et ses enseignants). +responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut être obtenu par l'entrée [formsemestre-programme](#formsemestre-programme) + +| attribut | type | commentaire | +|:-----------------------|:-------|:-------------------------------------------------| +| _**id**_ | int | identifiant unique | +| _**responsable_id**_ | int | id du responsable de module | +| _**computation_expr**_ | string | unused | +| _**module_id**_ | int | id du module | +| _**formsemestre_id**_ | int | id du formsemestre | +| _**moduleimpl_id**_ | int | _**redondance id_? | +| _**ens**_ | User# | liste des ids des enseignants du moduleimpl | +| _**module**_ | Module | | #### **`moduleimpl`** * **Méthode:** GET @@ -408,12 +460,24 @@ responsable et ses enseignants). * **Résultat:** Description du moduleimpl. * **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl.json.md) -### **Partition** +### **API Partition** +#### Structure Partition 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. +| attribut | type | commentaire | +|:----------------------|:-------|:-----------------------------------| +| _**id**_ | int | identifiant unique | +| _**partition_name**_ | string | nom de la partition | +| _**numero**_ | int | | +| _**bul_show_rank**_ | | affichage sur bulletin | +| _**groups_editable**_ | bool | verrou (liste des groupes) | +| _**formsemestre_id**_ | int | formsemestre hôte | +| _**show_in_lists**_ | bool | | +| _**groups**_ | Group* | liste des groupes de la partition | + #### **`formsemestre-partitions`** * **Méthode: GET** * **Paramètres:** `formsemestre_id` @@ -477,7 +541,7 @@ d'un nombre quelconque de groupes d'étudiants. * **Résultat:** Retire un étudiant des groupes de la partition. * **[Exemple de résultat](samples/sample_partition-remove_etudiant.json.md)** -### **Groupe** +### **API Groupe** #### **`partition-group-create`** * **Méthode: POST** @@ -549,7 +613,34 @@ d'un nombre quelconque de groupes d'étudiants. * **Résultat:** Retire un étudiant d'un groupe. * **[Exemple de résultat](samples/sample_group-remove_etudiant.json.md)** -### **Etudiant** +### **API Etudiant** +#### Structure Etudiant + +| attribut | type | commentaire | +|:-----------------|:----------|:---------------------------------| +| _id_ | int | id unique | +| _code_nip_ | string | non unique! | +| _code_ine_ | string | non unique! | +| _dept_id_ | | | +| _civilite_ | string | "M", "F" ou "X" | +| _nom_ | string | en majuscule | +| _nom_usuel_ | string | null si absent | +| _prenom_ | string | | +| | | **Format long** | +| _date_naissance_ | string | date ISO | +| _email_ | string | | +| _emailperso_ | string | | +| _admission_ | admission | | +| _adresses_ | adresse* | | +| _boursier_ | | | +| _dept_acronym_ | string | | +| _dept_id_ | string | département du lieu de naissance | +| _lieu_naissance_ | string | lieu de naissance (ville) | +| _nationalite_ | string | | +| _photo_filename_ | string | | +| _scodoc7_id_ | string | de la forme 'EID9999' | +| _statut_ | string | 'I', 'D' ou 'X' | + #### **`etudiants`** * **Méthode:** GET * **Routes:** `/etudiants @@ -660,7 +751,7 @@ d'un nombre quelconque de groupes d'étudiants. Si plusieurs objets étudiant ont le même code, on ramène le plus récemment inscrit. * **Exemple de résultat:** [etudiant.json](samples/sample_etudiant.json.md) -### Programme, Référentiel +### API Programme, Référentiel #### **`formation-export`** * **Méthode:** GET @@ -680,7 +771,7 @@ d'un nombre quelconque de groupes d'étudiants. * **Résultat:** Le référentiel de compétences d'une formation donnée (json). (_pas toujours présent_) * **Exemple de résultat:** [formation-referentiel_competences.json](samples/sample_formation-referentiel_competences.json.md) -### **Bulletin, Evaluations, Notes** +### ** API Bulletin, Evaluations, Notes** #### **formsemestre-bulletins** * **Méthode:** GET * **Paramètres:** `formsemestre_id` @@ -690,6 +781,13 @@ d'un nombre quelconque de groupes d'étudiants. * **Exemple de résultat:** [formsemestre-bulletins.json](samples/sample_formsemestre-bulletins.json.md) #### **etudiant-formsemestre-bulletin** +Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules +pour un formsemestre spécifié par son id. +Par défaut les valeurs numériques sont formattées en chaînes. Si format=raw, valeurs numériques +mais pas JSON compliant à cause des _NaN_. + +* **Exemple de résultat:** + * **Méthode:** GET * **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` * **Routes:** @@ -753,9 +851,54 @@ valeurs numériques mais pas JSON compliant à cause des _NaN_. * **Résultat:** Retourne la liste des notes d'une évaluation * **Exemple de résultat:** TODO XXX -### **User** +#### **formsemestre-etat_evals** +* **Méthode:** GET +* **Paramètres:** `formsemestre_id` +* **Routes:** `/formsemestre//etat_evals` +* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/etat_evals` +* **Résultat:** Retourne les informations sur l'état des évaluations d'un semestre donné +* **Exemple de résultat:** [formsemestre-etat_evals.json](samples/sample_formsemestre-etat_evals.json.md) -### Logos +#### **formsemestre-programme** +* **Méthode:** GET +* **Paramètres:** `dept`, `formsemestre_id` +* **Routes:** `/formsemestre//programme` +* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/programme` +* **Résultat:** Retourne la liste des UEs, modules, ressources et SAE d'un semestre. +* **Exemple de résultat:** [formsemestre-programme.json](samples/sample_formsemestre-programme.json.md) + +#### **formsemestre-resultats** +* **Méthode:** GET +* **Paramètres:** `formsemestre_id` +* **Query string: `format` +* **Route:** `/formsemestres/resultats` +* **Exemple d'utilisation:** `/api/formsemestre/1/resultats` +* **Résultat:** Retourne les résultats pour un formsemestre +* **Exemple de résultat:** [formsemestre-resultats.json](samples/sample_formsemestre-resultats.json.md) + +### **API User** +#### **user** +* **Méthode:** GET +* **Paramètres:** `user_id` +* **Route:** `/user/` +* **Exemple d'utilisation:** `/api/user/1` +* **Résultat:** Retourne la description d'un utilisateur. +* **Exemple de résultat:** [user.json](samples/sample_user.json.md) + + +### **API Jury** +#### **`formsemestre-decision_jury`** +* **Méthode:** GET +* **Paramètres:** `formsemestre_id` +* **Routes:** `/formsemestre//decision_jury` +* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/jury` +* **Résultat:** Retourne le récapitulatif des décisions jury +* **Exemple de résultat:** + ``` + XXX A COMPLETER + ``` + +### **API Logos** #### **`logos`** * **Méthode:** GET * **Paramètres:** `format` (json, xml), json par défaut @@ -789,136 +932,7 @@ XXX vérifier si on supporte XML et pour qui ? * **Résultat :** l'image (format png ou jpg) ------------------------------------------------------------------------------------------------------------------------------------------------------- - -## **Réserve** -### Étudiants inscrits et bulletins -#### * **`formsemestre-bulletins`** - * **Méthode:** GET - * **Paramètres:** `formsemestre_id` - * **Routes:** `/formsemestre//bulletins` - * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/bulletins` - * **Résultat:** tous les bulletins d'un formsemestre. - * **[Exemple de résultat](samples/sample_formsemestre-bulletins.json.md)** - -#### **formsemestre-etat_evals** - * **Méthode:** GET - * **Paramètres:** `formsemestre_id` - * **Routes:** `/formsemestre//etat_evals` - * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/etat_evals` - * **Résultat:** Retourne les informations sur l'état des évaluations d'un semestre donné - * **Exemple de résultat:** [formsemestre-etat_evals.json](samples/sample_formsemestre-etat_evals.json.md) - -#### **`formsemestre-decision_jury`** - * **Méthode:** GET - * **Paramètres:** `formsemestre_id` - * **Routes:** `/formsemestre//decision_jury` - * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/jury` - * **Résultat:** Retourne le récapitulatif des décisions jury - * **Exemple de résultat:** - ``` - XXX A COMPLETER - ``` - -### Évaluations - - -### 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. - - -#### **`absences`** - - * **Méthode:** GET - * **Paramètres:** `etudid`, `nip`, `ine` - * **Routes:** `/absences/etudid/` - * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/123456` - * **Résultat:** Retourne la liste des absences d'un étudiant donné - * **Exemple de résultat:** - ``` - [ - { - "jour": "2022-04-15", - "matin": true, - "estabs": true, - "estjust": true, - "description": "Retard bus", - "begin": "2022-04-15 08:00:00", - "end": "2022-04-15 11:59:59" - }, - { - ... - } - ] - ``` - -#### **`absences/just`** - - * **Méthode:** GET - * **Paramètres:** `etudid` - * **Routes:** `/absences/etudid//just` - * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/1/just` - * **Résultat:** Retourne la liste des absences justifiées d'un étudiant donné - * **Exemple de résultat:** - ``` - [ - { - "jour": "2022-04-15", - "matin": true, - "estabs": true, - "estjust": true, - "description": "Retard bus", - "begin": "2022-04-15 08:00:00", - "end": "2022-04-15 11:59:59" - }, - { - ... - } - ] - ``` - - -#### **`abs_groupe_etat`** - - * **Méthode:** GET - * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, - * **Routes:** `/absences/abs_group_etat/` ou `/absences/abs_group_etat/group_id//date_debut//date_fin/` - * **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/1` - * **Résultat:** Liste des absences d'un groupe entre deux dates. - * **Exemple de résultat:** - ``` - XXX A COMPLETER XXX with_boursier ?? - - * XXX ajouter méthode(s) de set abs - ``` - -### Jury - -#### **`jury_preparation`** - - * **Méthode:** GET - * **Paramètres:** `formsemestre_id` - * **Routes:** `/jury/formsemestre//preparation_jury` - * **Exemple d'utilisation:** `/ScoDoc/api/jury/formsemestre/1/preparation_jury` - * **Résultat:** Retourne la feuille de préparation du jury - * **Exemple de résultat:** - ``` - XXX A COMPLETER - ``` - -#### **`jury_decisions`** - - * **Méthode:** GET - * **Paramètres:** `formsemestre_id` - * **Routes:** `/jury/formsemestre//decisions_jury` - * **Exemple d'utilisation:** `/ScoDoc/api/jury/formsemestre/1/decisions_jury` - * **Résultat:** Retourne les décisions du jury suivant un formsemestre donné - * **Exemple de résultat:** - ``` - XXX A COMPLETER - ``` - - ### En savoir plus Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. diff --git a/docs/img/API_Chart.odg b/docs/img/API_Chart.odg index f2572f5dc..0d418385a 100644 Binary files a/docs/img/API_Chart.odg and b/docs/img/API_Chart.odg differ diff --git a/docs/img/API_Chart.svg b/docs/img/API_Chart.svg index e88a257af..77cc18674 100644 --- a/docs/img/API_Chart.svg +++ b/docs/img/API_Chart.svg @@ -92,7 +92,7 @@ - + @@ -794,8 +794,8 @@ - ? - id344 + ? + id359 @@ -803,8 +803,8 @@ - ? - id345 + ? + id360 @@ -1239,50 +1239,50 @@ - - - - logos + + + + logos - - - - / + + + + / - - - - <string:logo_name> + + + + <string:logo_name> - - - - user + + + + user - - - - / + + + + / - - - - <int:id> + + + + <int:id> @@ -1478,54 +1478,54 @@ - - - - partition + + + + partition - - - - / + + + + / - - - - <int:partition_id> + + + + <int:partition_id> - - - - / + + + + / - - + + - - + + - - + + @@ -1595,8 +1595,8 @@ - - + + @@ -1758,8 +1758,8 @@ - - + + @@ -2534,35 +2534,35 @@ - ? - id346 + ? + id361 - + - ? - id347 + ? + id362 - - - - ? - id348 + + + + ? + id363 - - - - ? - id349 + + + + ? + id364 @@ -2570,8 +2570,8 @@ - ? - id350 + ? + id365 @@ -2579,8 +2579,8 @@ - ? - id351 + ? + id366 @@ -2588,8 +2588,8 @@ - ? - id352 + ? + id367 @@ -2763,8 +2763,8 @@ - ? - id353 + ? + id368 @@ -2772,8 +2772,140 @@ - ? - id354 + ? + id369 + + + + + + + + ? + id370 + + + + + + + + ? + id371 + + + + + + + + ? + id372 + + + + + + + + ? + id373 + + + + + + + + ? + id374 + + + + + + + + moduleimpl + + + + + + + + / + + + + + + + + <int:moduleimpl_id> + + + + + + + + ? + id375 + + + + + + + + ? + id376 + + + + + + + + ? + id377 + + + + + + + + ? + id378 + + + + + + + + ? + id379 + + + + + + + + ? + id380 + + + + + + + + ? + id381 diff --git a/docs/samples/sample_departement-etudiants.json.md b/docs/samples/sample_departement-etudiants.json.md new file mode 100644 index 000000000..7db6114c6 --- /dev/null +++ b/docs/samples/sample_departement-etudiants.json.md @@ -0,0 +1,30 @@ +### etudiants + +`/api/etudiants/9537` + +```json +[ + { + "id": 1, + "code_nip": "11103639", + "code_ine": null, + "dept_id": 1, + "nom": "GYSELINCK", + "nom_usuel": null, + "prenom": "MARIE", + "civilite": "F" + }, + { + "id": 2, + "code_nip": "11102517", + "code_ine": null, + "dept_id": 1, + "nom": "IDRI", + "nom_usuel": null, + "prenom": "ANAIS", + "civilite": "F" + }, + ... +] +``` + diff --git a/docs/samples/sample_formsemestre-resultats.json.md b/docs/samples/sample_formsemestre-resultats.json.md index ec3b7804a..9d22956ac 100644 --- a/docs/samples/sample_formsemestre-resultats.json.md +++ b/docs/samples/sample_formsemestre-resultats.json.md @@ -40,6 +40,6 @@ "1735": 3784 } }, -... + ... ] ``` diff --git a/docs/samples/sample_user.json.md b/docs/samples/sample_user.json.md new file mode 100644 index 000000000..88f208961 --- /dev/null +++ b/docs/samples/sample_user.json.md @@ -0,0 +1,8 @@ +### user + +`/api/user/969` + +```json +"TODO" +``` +