DocAssiduites/docs/ScoDoc9API.md

675 lines
25 KiB
Markdown
Raw Normal View History

2021-09-14 12:31:16 +02:00
## API pour ScoDoc 9
2021-09-14 12:31:16 +02:00
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.
**Les clients de l'ancienne API ScoDoc 7 doivent être adaptés pour fonctionner avec ScoDoc 9.**
Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès en écrivant à la liste de diffusion.
L'API fournit des données JSON, sauf exception (bulletins).
2021-12-20 19:34:55 +01:00
Les objets ScoDoc manipulables sont identifiés par des id.
2021-09-14 12:31:16 +02:00
2021-11-16 15:17:07 +01:00
* etudid: étudiant
2021-11-19 11:18:02 +01:00
* formation_id: un programme de formation (page "programmes");
2021-09-14 12:31:16 +02:00
* ue_id: une UE dans un programme;
* matiere_id: une matière dans un programme;
2021-12-20 19:34:55 +01:00
* module_id: un module dans un programme;
* moduleimpl_id: un module réalisé dans un semestre;
2021-11-19 11:18:02 +01:00
* formsemestre_id: un "semestre" de formation.
2021-09-14 12:31:16 +02:00
2021-12-20 19:34:55 +01:00
(pour plus de précisions, voir la [doc interne](Internals.md))
2021-09-14 12:31:16 +02:00
2021-11-19 11:18:02 +01:00
L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`.
2021-09-14 12:31:16 +02:00
## Configuration de ScoDoc pour utiliser l'API
2021-09-14 12:31:16 +02:00
Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.
2021-10-28 10:23:28 +02:00
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.
2021-09-14 12:31:16 +02:00
En ligne de commande, cela peut se faire comme suit (voir détail des commandes
[sur le guide de configuration](GuideConfig.md)).
2021-09-14 12:31:16 +02:00
```
# se connecter comme utilisateur scodoc
su - scodoc
2021-09-14 12:31:16 +02:00
# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici APIView
flask edit-role LecteurAPI -a APIView
2021-09-14 12:31:16 +02:00
# Créer un nouvel utilisateur avec ce rôle:
flask user-create lecteur_api LecteurAPI @all
# 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)
2021-09-14 12:31:16 +02:00
Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149)
2021-11-09 21:37:37 +01:00
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).
2021-11-19 11:18:02 +01:00
### Accès à l'API REST
2021-11-09 21:37:37 +01:00
Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
#### Authentification
2021-11-19 11:18:02 +01:00
2021-12-30 09:58:58 +01:00
Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il
vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant
d'utiliser l'api suivant les droits correspondant à votre session.
2021-12-30 09:58:58 +01:00
Pour obtenir le jeton, il faut un compte sur ScoDoc (`user_name`et `password`).
Les autorisations et rôles sont gérés exactement comme pour l'application.
Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des
systèmes):
curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens
`SERVEUR` est l'adresse (IP ou nom) de votre serveur.
La réponse doit ressembler à ceci:
```
{
"token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
}
```
Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple
complet en python d'interrogation de l'API.
#### Codes HTTP
2021-12-30 09:58:58 +01:00
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.
2021-11-09 21:37:37 +01:00
2021-11-16 15:17:07 +01:00
Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs.
2021-11-09 21:37:37 +01:00
2021-11-16 15:17:07 +01:00
* [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK.
* [400](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Paramètre manquant, ou valeur incorrecte.
* [401](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Authentification nécessaire. (jeton non précisé ou invalide)
* [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403) : Action non autorisée. (crédits épuisés, URL non autorisée, etc)
* [404](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/404) : Page inaccessible. (URL inconnue / impossible d'accéder à l'adresse)
* [406](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/406) : Le JSON indiqué en données POST n'est pas valide.
* [408](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/408) : Dépassement du temps maximal autorisé pour laudit.
* [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur inconnue, contactez-nous.
* [503](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/503) : L'API est momentanément indisponible, réessayez dans quelques minutes.
2021-11-09 21:37:37 +01:00
2021-11-16 15:17:07 +01:00
### Départements
* **`departements`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
* **Routes:** `/departements`
* **Exemple d'utilisation:** `/api/departements`
2021-11-16 15:17:07 +01:00
* **Résultat:** Liste des id de départements.
* **Exemple de résultat:** `[1, 2, 3, ...]`
* **`liste_etudiants`**
* **Méthode:** GET
* **Paramètres:** `dept`, `formsemestre_id`
* **Routes:** `/departements/<string:dept>/etudiants/liste` ou `/api/departements/<string:dept>/etudiants/liste/<int:formsemestre_id>`
* **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_courant`**
* **Méthode:** GET
* **Paramètres:** `dept`
* **Routes:** `/departements/<string:dept>/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_)
* **`referentiel_competences`**
* **Méthode:** GET
* **Paramètres:** `dept`, `formation_id`
* **Routes:** `/departements/<string:dept>/formations/<int:formation_id>/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
* **`semestre_index`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
* **Paramètres:** `dept`, `formsemestre_id`
* **Routes:** `/departements/<string:dept>/formsemestre/<string:formsemestre_id>/programme`
* **Exemple d'utilisation:** `api/departements/MMI/formsemestre/1/programme`
* **Résultat:** Retourne la liste des Ues, ressources et SAE d'un semestre (json).
### Etudiants
* **`etudiants_courant`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
* **Routes:** `/etudiants/courant`
* **Exemple d'utilisation:** `/api/etudiants/courant`
* **Résultat:** Retourne la liste des étudiants courant (json).
2021-11-16 15:17:07 +01:00
* **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"
},
{
"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/<int:etudid>` ou `/etudiant/nip/<int:nip>` ou `/etudiant/ine/<int: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/<int:etudid>/formsemestres` ou `/etudiant/nip/<int:nip>/formsemestres` ou `/etudiant/ine/<int: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`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine`
* **Routes:** `/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin` ou `/etudiant/nip/<int:nip>/formsemestre/<int:formsemestre_id>/bulletin` ou `/etudiant/ine/<int:ine>/formsemestre/<int:formsemestre_id>/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)
2021-11-16 15:17:07 +01:00
* **`etudiant_groups`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine`
* **Routes:** `/etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/nip/<int:nip>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/ine/<int:ine>/semestre/<int:formsemestre_id>/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"
},
...
]
```
2021-09-14 12:31:16 +02:00
## Programmes de formations
* **`formations`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
* **Paramètres:** `formation_id` (_optionnel, si absent, liste toutes les formations_)
* **Routes:** `/ScoDoc/api/formations` **ou** `/ScoDoc/api/formations/<int:formation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formations` **ou** `/ScoDoc/api/formations/1`
2021-11-16 15:17:07 +01:00
* **Résultat:** Liste des formations.
2021-11-18 17:16:04 +01:00
* **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]`
2021-11-19 11:18:02 +01:00
* TODO: détailler le contenu publié
2021-11-16 15:17:07 +01:00
2021-09-14 12:31:16 +02:00
2021-11-18 17:16:04 +01:00
* **`formation_export`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
2021-11-19 11:18:02 +01:00
* **Paramètres:** `formation_id`, `export_ids` (_par défaut "faux"_)
* **Routes:** `/ScoDoc/api/formations/formation_export/<int:formation_id>?format=<string:format>&export_ids=<int:export_ids>`
* **Exemple d'utilisation:** `/ScoDoc/api/formations/formation_export/596` **ou** `/ScoDoc/api/formations/formation_export/596?format=xml&export_ids=1`
2021-11-16 15:17:07 +01:00
* **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": ...
}
```
2021-11-18 17:16:04 +01:00
### UE
* **`UEs`**
* **Méthode:** GET
* **Paramètres:** `dept`, `̀semestre`
* **Routes:** `/ScoDoc/api/departements/<string:dept>/formations/programme/<string:semestre>`
* **Exemple d'utilisation:** `̀/ScoDoc/api/departements/MMI/formations/programme/INFO-DUT-FI-S1-2014`
* **Résultat:** Liste des UEs, ressources et SAE d'un semestre
2021-11-16 15:17:07 +01:00
2021-11-19 11:18:02 +01:00
2021-11-18 17:16:04 +01:00
### Semestres de formation
2021-11-19 11:18:02 +01:00
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`.
2021-11-18 17:16:04 +01:00
2021-11-19 11:18:02 +01:00
* **`formsemestre`**
2021-11-18 17:16:04 +01:00
* **Méthode:** GET
2021-11-19 11:18:02 +01:00
* **Paramètres:** `formsemestre_id` ou `etape_apo`, `format`(json ou xml)
* **Routes:** `/ScoDoc/api/formations/formsemestre/<int:formsemestre_id>`, `/ScoDoc/api/formsemestre/apo/<etape_apo>`
* **Exemple d'utilisation:** `/ScoDoc/api/formations/formsemestre/12`
2021-11-19 11:18:02 +01:00
* **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
2021-11-19 16:36:03 +01:00
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:
2021-09-14 12:31:16 +02:00
2021-11-16 15:17:07 +01:00
* **Département** (RT, GEII, INFO...) (= paramètre `DeptName`, en majuscules)
2021-11-19 11:18:02 +01:00
* **Nom parcours:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
2021-11-16 15:17:07 +01:00
* **Modalité:** FI, FC, FA
2021-11-19 11:18:02 +01:00
* **"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
2021-11-19 11:18:02 +01:00
(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).
2021-09-14 12:31:16 +02:00
2021-11-16 15:17:07 +01:00
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI)
2021-09-14 12:31:16 +02:00
### Modules de formation
2021-11-19 11:18:02 +01:00
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.
2021-11-19 16:36:03 +01:00
2021-11-19 11:18:02 +01:00
* **`moduleimpl`**
* **Méthode:** GET
* **Paramètres**: `formsemestre_id` ou `moduleimpl_id`
* **Routes:** `/ScoDoc/api/formations/moduleimpl/<int:moduleimpl_id>` **ou** `/ScoDoc/api/formations/moduleimpl/<int:moduleimpl_id>/formsemestre/<int:formsemestre_id>`
2021-11-19 11:18:02 +01:00
* **Résultat:** liste de moduleimpl
* **Exemple de résultat:**
TODO
2021-09-14 12:31:16 +02:00
### Groupes et partitions
2021-11-19 16:36:03 +01:00
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.
2021-09-14 12:31:16 +02:00
2021-11-19 11:18:02 +01:00
* **`partition`**
2021-11-16 15:17:07 +01:00
* **Méthode: GET**
2021-11-18 17:16:04 +01:00
* **Paramètres:** `formsemestre_id`
* **Routes:** `/ScoDoc/api/partitions/<int:formsemestre_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/48`
2021-11-19 11:18:02 +01:00
* **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"
}
2021-11-16 15:17:07 +01:00
]
},
{
"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
}
]
}
]
```
2021-09-14 12:31:16 +02:00
2021-11-19 11:18:02 +01:00
* **`groups`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
2021-11-18 17:16:04 +01:00
* **Paramètres:** `formsemestre_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I`
* **Routes:** `/ScoDoc/api/partitions/formsemestre/<int:formsemestre_id>/groups/group_ids?with_codes=<bool:with_codes>&all_groups=<bool:all_groups>&etat=None|I`
* **Exemple d'utilisation:** `/ScoDoc/api/partitions/formsemestre/213/groups/123?with_codes=True`
2021-11-16 15:17:07 +01:00
* **Résultat:** Liste des étudiants dans un groupe.
* **Exemple de résultat au format XML:** (_avec `with_codes=True`_)
2021-11-19 16:36:03 +01:00
```
<group_list origin="" caption="soit 21 étudiants inscrits et 2 démissionaires." id="gt_711068">
<etud>
<nom value="TOTO"/>
<prenom value="Marc"/>
<etat value="I"/>
<email value="toto@example.com"/>
<etudid value="9876"/>
<code_nip value="987654"/>
<code_ine value=""/>
</etud>
<etud>
<nom value="ALVIS SAMOS"/>
<prenom value="NATHALIE"/>
<etat value="I"/>
<email value="xxx@example.com"/>
<etudid value="12345"/>
<code_nip value="12345678"/>
<code_ine value=""/>
</etud>
</group_list>
```
* **Exemple de résultat au format JSON:**
```
[
{
"etat":"I",
"emailperso":null,
"prenom":"Dalil",
"nom_disp":"CLINTO",?
2021-11-19 16:36:03 +01:00
"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"
},
...
]
```
2021-11-16 15:17:07 +01:00
* **`set_groups`**
2021-11-16 15:17:07 +01:00
* **Méthode:** POST
* **Paramètres:** `partition_id`, `groups`, `groups_to_delete`, `groups_to_create`
* **Routes:** `/ScoDoc/api/partitions/set_groups?partition_id=<int:partition_id>&groups=<int:groups>&groups_to_delete=<int:groups_to_delete>&groups_to_create=<int:groups_to_create>`
* **Exemple d'utilisation:** `/ScoDoc/api/partitions/set_groups?partition_id=65&groups=77&groups_to_delete=8&groups_to_create=4`
2021-11-16 15:17:07 +01:00
* **Résultat:** Set les groups.
2021-11-19 16:36:03 +01:00
TODO: à changer, passer les paramètres dans le corps de la requête
2021-09-14 12:31:16 +02:00
### Bulletins de notes
* **`evaluations`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
2021-11-19 11:18:02 +01:00
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/ScoDoc/api/evaluations/<int:moduleimpl_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/54`
2021-11-19 11:18:02 +01:00
* **Résultat:** Liste des évaluations à partir de l'id d'un moduleimpl.
2021-11-16 15:17:07 +01:00
* **Exemple de résultat:** `[eval_1, eval_2, eval_3, ...]`
2021-11-19 11:18:02 +01:00
* **`evaluation_notes`**
2021-11-16 15:17:07 +01:00
* **Méthode**: GET
2021-11-19 11:18:02 +01:00
* **Paramètres**: `evaluation_id`
* **Routes:** `/ScoDoc/api/evaluations/eval_notes/<int:evaluation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_notes/24`
2021-11-16 15:17:07 +01:00
* **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée.
* **Exemple de résultat:**
2021-11-19 16:36:03 +01:00
```
[
{
"84": "13",
"85": "15",
"86": "9",
...
}
]
```
2021-11-19 11:18:02 +01:00
* **`evaluation_set_notes`**
2021-11-16 15:17:07 +01:00
* **Méthode:** POST
* **Paramètres:** `eval_id`, `etudid`, `note`
* **Routes:** `/ScoDoc/api/evaluations/eval_set_notes?eval_id=<int:eval_id>&etudid=<int:etudid>&note=<int:note>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_set_notes?eval_id=6&etudid=456&note=15`
2021-11-16 15:17:07 +01:00
* **Résultat:** Set les notes d'une évaluation pour un étudiant donné.
2021-11-19 11:18:02 +01:00
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.
* **`absences`**
* **Méthode:** GET
* **Paramètres:** `etudid`, `abs_just_only, format`, `abs_just_only` (_spécifie si on veut les absences justifiées ou non_).
* **Routes:** `/ScoDoc/api/absences/<int:etudid>`
* **Exemple d'utilisation:** `/ScoDoc/api/absences/54`
* **Résultat:** Liste des absences d'un étudiant donné.
* **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=<int: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
* **Paramètres:** `date_debut`, `date_fin`, `demi_journee`, `etudid`
* **Body de la requête:** `date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&etudid=<int:etudid>`
* **Exemple d'utilisation:** `date_debut=2004-05-03&date_fin=2004-06-07&demi_journee=2&etudid=451`
* **Résultat:** *html*
* **`abs_annule_justif`**
* **Méthode:** POST
* **Paramètres:** `context`, `date_debut`, `date_fin`, `demi_journee`
* **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*
* **`abs_groupe_etat`**
2021-11-16 15:17:07 +01:00
* **Méthode:** GET
* **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html`
* **Routes:** `/ScoDoc/api/absences/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin`
* **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30`
2021-11-16 15:17:07 +01:00
* **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates.
* **Exemple de résultat:** si `format="json"` cela donne:
```
[
{
"boursier": "N",
"nbabs": "9",
"nbabsjust": "2",
"nbabsnonjust": "7",
"nbjustifs_noabs": "0",
"nomprenom": "Mme Poisson Dodouce",
2021-11-19 11:18:02 +01:00
"etudid": "12345"
2021-11-16 15:17:07 +01:00
},
...
]
```
### Logos
2021-12-20 17:44:45 +01:00
* **`liste des logos globaux`**
* **Méthode:** GET
* **Paramètres:** `format` (json, xml), json par défaut
* **Route :** `/ScoDoc/api/logos`
* **Exemple d'utilisation :** `/ScoDoc/api/logos?format=xml`
2021-12-20 17:44:45 +01:00
* **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`**
2021-12-20 17:44:45 +01:00
* **Méthode:** GET
* **Paramètres :** Aucun
* **Route:** `/ScoDoc/api/logos/<string:nom>`
* **Exemple d'utilisation :** `/ScoDoc/api/logos/header`
2021-12-20 17:44:45 +01:00
* **Résultat :** l'image (format png ou jpg)
2021-12-20 17:44:45 +01:00
* **`logo d'un département`**
* **Méthode:** GET
* **Paramètres:** `format` (json, xml)
* **Route :** `/ScoDoc/api/departements/<string:dept>/logos`
* **Exemple d'utilisation :** `/ScoDoc/api/MMI/logos`
2021-12-20 17:44:45 +01:00
* **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`**
2021-12-20 17:44:45 +01:00
* **Méthode:** GET
* **Paramètres :** Aucun
* **Route:** `/ScoDoc/api/departements/<string:dept>/logos/<string:nom>`
* **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/logos/header`
2021-12-20 17:44:45 +01:00
* **Résultat :** l'image (format png ou jpg)
2021-09-14 12:31:16 +02:00
### En savoir plus
Voir exemples d'utilisation de l'API en Python, dans `tests/api/`.
2021-09-14 12:31:16 +02:00
## 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/<etudid>/bul/<formsemestre_id>`)
- `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?)
- `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/<etudid>`)
- `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/<dept>/Scolarite/`, et répondent en GET et
en POST.
Note:
- `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.