DocAssiduites/docs/ScoDoc9API.md
2022-05-02 09:41:45 +02:00

1550 lines
51 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## 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.
**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).
Les objets ScoDoc manipulables sont identifiés par des id.
* etudid: étudiant
* formation_id: un programme de formation (page "programmes");
* ue_id: une UE dans un programme;
* matiere_id: une matière dans un programme;
* module_id: un module dans un programme;
* moduleimpl_id: un module réalisé dans un semestre;
* formsemestre_id: un "semestre" de formation.
(pour plus de précisions, voir la [doc interne](Internals.md))
L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`.
## Configuration de ScoDoc pour utiliser l'API
Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.
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.
En ligne de commande, cela peut se faire comme suit (voir détail des commandes
[sur le guide de configuration](GuideConfig.md)).
```
# se connecter comme utilisateur scodoc
su - scodoc
# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici APIView
flask edit-role LecteurAPI -a APIView
# 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)
Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149)
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
Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
#### 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
d'utiliser l'api suivant les droits correspondant à votre session.
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
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.
Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs.
* [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.
#### 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
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:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
* **Modalité:** FI, FC, FA
* **"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
(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).
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI)
### Départements
* **`departements`**
* **Méthode:** GET
* **Routes:** `/departements`
* **Exemple d'utilisation:** `/api/departements`
* **Résultat:** Liste des départements.
* **Exemple de résultat:**
```
[
{
"id": 1,
"acronym": "TAPI",
"description": null,
"visible": true,
"date_creation": "Fri, 15 Apr 2022 12:19:28 GMT"
},
{
"id": 2,
"acronym": "MMI",
"description": null,
"visible": false,
"date_creation": "Fri, 18 Apr 2022 11:20:8 GMT"
},
...
]
```
* **`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)
* **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"
},
...
]
```
* **`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_)
* **Exemple de résultat:**
```
[
{
"titre": "master machine info",
"gestion_semestrielle": false,
"scodoc7_id": null,
"date_debut": "01/09/2021",
"bul_bgcolor": null,
"date_fin": "15/12/2022",
"resp_can_edit": false,
"dept_id": 1,
"etat": true,
"resp_can_change_ens": false,
"id": 1,
"modalite": "FI",
"ens_can_edit_eval": false,
"formation_id": 1,
"gestion_compensation": false,
"elt_sem_apo": null,
"semestre_id": 1,
"bul_hide_xml": false,
"elt_annee_apo": null,
"block_moyennes": false,
"formsemestre_id": 1,
"titre_num": "master machine info semestre 1",
"date_debut_iso": "2021-09-01",
"date_fin_iso": "2022-12-15",
"responsables": [
3,
2
]
},
...
]
```
* **`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`**
* **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).
* **Exemple de résultat:**
```
{
"ues": [
{
"type": 0,
"formation_id": 1,
"ue_code": "UCOD11",
"id": 1,
"ects": 12,
"acronyme": "RT1.1",
"is_external": false,
"numero": 1,
"code_apogee": "",
"titre": "Administrer les réseaux et lInternet",
"coefficient": 0,
"semestre_idx": 1,
"color": "#B80004",
"ue_id": 1
},
...
],
"ressources": [
{
"titre": "Fondamentaux de la programmation",
"coefficient": 1,
"module_type": 2,
"id": 17,
"ects": null,
"abbrev": null,
"ue_id": 3,
"code": "R107",
"formation_id": 1,
"heures_cours": 0,
"matiere_id": 3,
"heures_td": 0,
"semestre_id": 1,
"heures_tp": 0,
"numero": 70,
"code_apogee": "",
"module_id": 17
},
...
],
"saes": [
{
"titre": "Se présenter sur Internet",
"coefficient": 1,
"module_type": 3,
"id": 14,
"ects": null,
"abbrev": null,
"ue_id": 3,
"code": "SAE14",
"formation_id": 1,
"heures_cours": 0,
"matiere_id": 3,
"heures_td": 0,
"semestre_id": 1,
"heures_tp": 0,
"numero": 40,
"code_apogee": "",
"module_id": 14
},
...
]
}
```
### Etudiants
* **`etudiants_courant`**
* **Méthode:** GET
* **Routes:** `/etudiants/courant` ou `/etudiants/courant/long`
* **Exemple d'utilisation:** `/api/etudiants/courant`
* **Résultat:** Retourne la liste des étudiants courant (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"
},
{
"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)
* **Exemple de résultat:**
```
[
{
"date_fin": "31/08/2022",
"resp_can_edit": false,
"dept_id": 1,
"etat": true,
"resp_can_change_ens": true,
"id": 1,
"modalite": "FI",
"ens_can_edit_eval": false,
"formation_id": 1,
"gestion_compensation": false,
"elt_sem_apo": null,
"semestre_id": 1,
"bul_hide_xml": false,
"elt_annee_apo": null,
"titre": "Semestre test",
"block_moyennes": false,
"scodoc7_id": null,
"date_debut": "01/09/2021",
"gestion_semestrielle": false,
"bul_bgcolor": "white",
"formsemestre_id": 1,
"titre_num": "Semestre test semestre 1",
"date_debut_iso": "2021-09-01",
"date_fin_iso": "2022-08-31",
"responsables": []
}
]
```
* **`etudiant_bulletin_semestre`**
* **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)
* **Exemple de résultat:**
```
{
"version": "0",
"type": "BUT",
"date": "2022-04-27T07:18:16.450634Z",
"publie": true,
"etudiant": {
"civilite": "X",
"code_ine": "1",
"code_nip": "1",
"date_naissance": "",
"email": "SACHA.COSTA@example.com",
"emailperso": "",
"etudid": 1,
"nom": "COSTA",
"prenom": "SACHA",
"nomprenom": "Sacha COSTA",
"lieu_naissance": "",
"dept_naissance": "",
"nationalite": "",
"boursier": "",
"fiche_url": "/ScoDoc/TAPI/Scolarite/ficheEtud?etudid=1",
"photo_url": "/ScoDoc/TAPI/Scolarite/get_photo_image?etudid=1&size=small",
"id": 1,
"codepostaldomicile": "",
"paysdomicile": "",
"telephonemobile": "",
"typeadresse": "domicile",
"domicile": "",
"villedomicile": "",
"telephone": "",
"fax": "",
"description": ""
},
"formation": {
"id": 1,
"acronyme": "BUT R&amp;T",
"titre_officiel": "Bachelor technologique réseaux et télécommunications",
"titre": "BUT R&amp;T"
},
"formsemestre_id": 1,
"etat_inscription": "I",
"options": {
"show_abs": true,
"show_abs_modules": false,
"show_ects": true,
"show_codemodules": false,
"show_matieres": false,
"show_rangs": true,
"show_ue_rangs": true,
"show_mod_rangs": true,
"show_moypromo": false,
"show_minmax": false,
"show_minmax_mod": false,
"show_minmax_eval": false,
"show_coef": true,
"show_ue_cap_details": false,
"show_ue_cap_current": true,
"show_temporary": true,
"temporary_txt": "Provisoire",
"show_uevalid": true,
"show_date_inscr": true
},
"ressources": {
"R101": {
"id": 1,
"titre": "Initiation aux réseaux informatiques",
"code_apogee": null,
"url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=1",
"moyenne": {},
"evaluations": [
{
"id": 1,
"description": "eval1",
"date": "2022-04-20",
"heure_debut": "08:00",
"heure_fin": "09:00",
"coef": "01.00",
"poids": {
"RT1.1": 1
},
"note": {
"value": "12.00",
"min": "00.00",
"max": "18.00",
"moy": "10.88"
},
"url": "/ScoDoc/TAPI/Scolarite/Notes/evaluation_listenotes?evaluation_id=1"
}
]
}
},
"saes": {
"SAE11": {
"id": 2,
"titre": "Se sensibiliser à l&apos;hygiène informatique et à la cybersécurité",
"code_apogee": null,
"url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=2",
"moyenne": {},
"evaluations": []
}
},
"ues": {
"RT1.1": {
"id": 1,
"titre": "Administrer les réseaux et lInternet",
"numero": 1,
"type": 0,
"color": "#B80004",
"competence": null,
"moyenne": {
"value": "08.50",
"min": "06.00",
"max": "16.50",
"moy": "11.31",
"rang": "12",
"total": 16
},
"bonus": "00.00",
"malus": "00.00",
"capitalise": null,
"ressources": {
"R101": {
"id": 1,
"coef": 12,
"moyenne": "12.00"
}
},
"saes": {
"SAE11": {
"id": 2,
"coef": 16,
"moyenne": "~"
}
},
"ECTS": {
"acquis": 0,
"total": 12
}
},
"semestre": {
"etapes": [],
"date_debut": "2021-09-01",
"date_fin": "2022-08-31",
"annee_universitaire": "2021 - 2022",
"numero": 1,
"inscription": "",
"groupes": [],
"absences": {
"injustifie": 1,
"total": 2
},
"ECTS": {
"acquis": 0,
"total": 30
},
"notes": {
"value": "10.60",
"min": "02.40",
"moy": "11.05",
"max": "17.40"
},
"rang": {
"value": "10",
"total": 16
}
}
}
}
```
* **`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"
},
...
]
```
## Programmes de formations
* **`formations`**
* **Méthode:** GET
* **Routes:** `/ScoDoc/api/formations`
* **Exemple d'utilisation:** `/ScoDoc/api/formations`
* **Résultat:** Liste des formations.
* **Exemple de résultat:**
```
[
{
"id": 1,
"acronyme": "BUT R&amp;T",
"titre_officiel": "Bachelor technologique réseaux et télécommunications",
"formation_code": "V1RET",
"code_specialite": null,
"dept_id": 1,
"titre": "BUT R&amp;T",
"version": 1,
"type_parcours": 700,
"referentiel_competence_id": null,
"formation_id": 1
},
...
]
```
* **`formations_by_id`**
* **Méthode:** GET
* **Paramètres:** `formation_id`
* **Routes:** `/formations/<int:formation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formations/1`
* **Résultat:** Retourne une formation en fonction d'un id donné
* **Exemple de résultat:**
```
{
"id": 1,
"acronyme": "BUT R&amp;T",
"titre_officiel": "Bachelor technologique réseaux et télécommunications",
"formation_code": "V1RET",
"code_specialite": null,
"dept_id": 1,
"titre": "BUT R&amp;T",
"version": 1,
"type_parcours": 700,
"referentiel_competence_id": null,
"formation_id": 1
}
```
* **`formation_export_by_formation_id`**
* **Méthode:** GET
* **Paramètres:** `formation_id`, `export_ids` (False par défaut)
* **Routes:** `/formations/formation_export/<int:formation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formations/formation_export/1`
* **Résultat:** Retourne la formation, avec UE, matières, modules
* **Exemple de résultat:**
```
{
"id": 1,
"acronyme": "BUT R&amp;T",
"titre_officiel": "Bachelor technologique réseaux et télécommunications",
"formation_code": "V1RET",
"code_specialite": null,
"dept_id": 1,
"titre": "BUT R&amp;T",
"version": 1,
"type_parcours": 700,
"referentiel_competence_id": null,
"formation_id": 1,
"ue": [
{
"acronyme": "RT1.1",
"numero": 1,
"titre": "Administrer les réseaux et lInternet",
"type": 0,
"ue_code": "UCOD11",
"ects": 12,
"is_external": false,
"code_apogee": "",
"coefficient": 0,
"semestre_idx": 1,
"color": "#B80004",
"reference": 1,
"matiere": [
{
"titre": "Administrer les réseaux et lInternet",
"numero": 1,
"module": [
{
"titre": "Initiation aux réseaux informatiques",
"abbrev": "Init aux réseaux informatiques",
"code": "R101",
"heures_cours": 0,
"heures_td": 0,
"heures_tp": 0,
"coefficient": 1,
"ects": "",
"semestre_id": 1,
"numero": 10,
"code_apogee": "",
"module_type": 2,
"coefficients": [
{
"ue_reference": "1",
"coef": "12.0"
},
{
"ue_reference": "2",
"coef": "4.0"
},
{
"ue_reference": "3",
"coef": "4.0"
}
]
},
{
"titre": "Se sensibiliser à l&apos;hygiène informatique et à la cybersécurité",
"abbrev": "Hygiène informatique",
"code": "SAE11",
"heures_cours": 0,
"heures_td": 0,
"heures_tp": 0,
"coefficient": 1,
"ects": "",
"semestre_id": 1,
"numero": 10,
"code_apogee": "",
"module_type": 3,
"coefficients": [
{
"ue_reference": "1",
"coef": "16.0"
}
]
}
]
}
]
}
]
}
```
### 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`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1`
* **Résultat:** Retourne l'information sur le formsemestre correspondant au formsemestre_id
* **Exemple de résultat:**
```
{
"date_fin": "31/08/2022",
"resp_can_edit": false,
"dept_id": 1,
"etat": true,
"resp_can_change_ens": true,
"id": 1,
"modalite": "FI",
"ens_can_edit_eval": false,
"formation_id": 1,
"gestion_compensation": false,
"elt_sem_apo": null,
"semestre_id": 1,
"bul_hide_xml": false,
"elt_annee_apo": null,
"titre": "Semestre test",
"block_moyennes": false,
"scodoc7_id": null,
"date_debut": "01/09/2021",
"gestion_semestrielle": false,
"bul_bgcolor": "white",
"formsemestre_id": 1,
"titre_num": "Semestre test semestre 1",
"date_debut_iso": "2021-09-01",
"date_fin_iso": "2022-08-31",
"responsables": []
}
```
* **`formsemestre_apo`**
* **Méthode:** GET
* **Paramètres:** `etape_apo`
* **Routes:** `/formsemestre/apo/<string:etape_apo>`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1`
* **Résultat:** Retourne les informations sur les formsemestres
* **Exemple de résultat:**
```
{
"date_fin": "31/08/2022",
"resp_can_edit": false,
"dept_id": 1,
"etat": true,
"resp_can_change_ens": true,
"id": 1,
"modalite": "FI",
"ens_can_edit_eval": false,
"formation_id": 1,
"gestion_compensation": false,
"elt_sem_apo": null,
"semestre_id": 1,
"bul_hide_xml": false,
"elt_annee_apo": null,
"titre": "Semestre test",
"block_moyennes": false,
"scodoc7_id": null,
"date_debut": "01/09/2021",
"gestion_semestrielle": false,
"bul_bgcolor": "white",
"formsemestre_id": 1,
"titre_num": "Semestre test semestre 1",
"date_debut_iso": "2021-09-01",
"date_fin_iso": "2022-08-31",
"responsables": []
}
```
* **`etudiant_bulletin`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `dept`, `etudid`, `nip`, `ine`
* **Routes:** `/formsemestre/<int:formsemestre_id>/departements/<string:dept>/etudiant/etudid/<int:etudid>/bulletin` ou `/formsemestre/<int:formsemestre_id>/departements/<string:dept>/etudiant/nip/<int:nip>/bulletin` ou `/formsemestre/<int:formsemestre_id>/departements/<string:dept>/etudiant/ine/<int:ine>/bulletin`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/departements/MMI/etudiant/etudid/1/bulletin`
* **Résultat:** Retourne le bulletin de note d'un étudiant
* **Exemple de résultat:**
```
{
"etudid": 1,
"formsemestre_id": 1,
"date": "2022-04-27T10:44:47.448094",
"publie": true,
"etapes": [],
"etudiant": {
"etudid": 1,
"code_nip": "1",
"code_ine": "1",
"nom": "COSTA",
"prenom": "Sacha",
"civilite": "",
"photo_url": "/ScoDoc/TAPI/Scolarite/get_photo_image?etudid=1&amp;size=small",
"email": "SACHA.COSTA@example.com",
"emailperso": "",
"sexe": ""
},
"note": {
"value": "10.60",
"min": "-",
"max": "-",
"moy": "-"
},
"rang": {
"value": "10",
"ninscrits": 16
},
"rang_group": [
{
"group_type": "TD",
"group_name": "",
"value": "",
"ninscrits": ""
}
],
"note_max": {
"value": 20
},
"bonus_sport_culture": {
"value": 0
},
"ue": [
{
"id": 1,
"numero": "1",
"acronyme": "RT1.1",
"titre": "Administrer les réseaux et lInternet",
"note": {
"value": "08.50",
"min": "06.00",
"max": "16.50",
"moy": "11.31"
},
"rang": "12",
"effectif": 16,
"ects": "12",
"code_apogee": "",
"module": [
{
"id": 1,
"code": "R101",
"coefficient": 1,
"numero": 10,
"titre": "Initiation aux réseaux informatiques",
"abbrev": "Init aux réseaux informatiques",
"note": {
"value": "12.00",
"moy": "-",
"max": "-",
"min": "-",
"nb_notes": "-",
"nb_missing": "-",
"nb_valid_evals": "-"
},
"code_apogee": "",
"evaluation": [
{
"jour": "2022-04-20",
"heure_debut": "08:00:00",
"heure_fin": "09:00:00",
"coefficient": 1,
"evaluation_type": 0,
"evaluation_id": 1,
"description": "eval1",
"note": "12.00"
}
]
}
]
}
],
"ue_capitalisee": [],
"absences": {
"nbabs": 2,
"nbabsjust": 1
},
"appreciation": []
}
```
* **`bulletins`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/bulletins`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/bulletins`
* **Résultat:** Retourne les bulletins d'un formsemestre donné
* **Exemple de résultat:**
```
[
{
"version": "0",
"type": "BUT",
"date": "2022-04-27T07:18:16.450634Z",
"publie": true,
"etudiant": {
"civilite": "X",
"code_ine": "1",
"code_nip": "1",
"date_naissance": "",
"email": "SACHA.COSTA@example.com",
"emailperso": "",
"etudid": 1,
"nom": "COSTA",
"prenom": "SACHA",
"nomprenom": "Sacha COSTA",
"lieu_naissance": "",
"dept_naissance": "",
"nationalite": "",
"boursier": "",
"fiche_url": "/ScoDoc/TAPI/Scolarite/ficheEtud?etudid=1",
"photo_url": "/ScoDoc/TAPI/Scolarite/get_photo_image?etudid=1&size=small",
"id": 1,
"codepostaldomicile": "",
"paysdomicile": "",
"telephonemobile": "",
"typeadresse": "domicile",
"domicile": "",
"villedomicile": "",
"telephone": "",
"fax": "",
"description": ""
},
"formation": {
"id": 1,
"acronyme": "BUT R&amp;T",
"titre_officiel": "Bachelor technologique réseaux et télécommunications",
"titre": "BUT R&amp;T"
},
"formsemestre_id": 1,
"etat_inscription": "I",
"options": {
"show_abs": true,
"show_abs_modules": false,
"show_ects": true,
"show_codemodules": false,
"show_matieres": false,
"show_rangs": true,
"show_ue_rangs": true,
"show_mod_rangs": true,
"show_moypromo": false,
"show_minmax": false,
"show_minmax_mod": false,
"show_minmax_eval": false,
"show_coef": true,
"show_ue_cap_details": false,
"show_ue_cap_current": true,
"show_temporary": true,
"temporary_txt": "Provisoire",
"show_uevalid": true,
"show_date_inscr": true
},
"ressources": {
"R101": {
"id": 1,
"titre": "Initiation aux réseaux informatiques",
"code_apogee": null,
"url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=1",
"moyenne": {},
"evaluations": [
{
"id": 1,
"description": "eval1",
"date": "2022-04-20",
"heure_debut": "08:00",
"heure_fin": "09:00",
"coef": "01.00",
"poids": {
"RT1.1": 1
},
"note": {
"value": "12.00",
"min": "00.00",
"max": "18.00",
"moy": "10.88"
},
"url": "/ScoDoc/TAPI/Scolarite/Notes/evaluation_listenotes?evaluation_id=1"
}
]
}
},
"saes": {
"SAE11": {
"id": 2,
"titre": "Se sensibiliser à l&apos;hygiène informatique et à la cybersécurité",
"code_apogee": null,
"url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=2",
"moyenne": {},
"evaluations": []
}
},
"ues": {
"RT1.1": {
"id": 1,
"titre": "Administrer les réseaux et lInternet",
"numero": 1,
"type": 0,
"color": "#B80004",
"competence": null,
"moyenne": {
"value": "08.50",
"min": "06.00",
"max": "16.50",
"moy": "11.31",
"rang": "12",
"total": 16
},
"bonus": "00.00",
"malus": "00.00",
"capitalise": null,
"ressources": {
"R101": {
"id": 1,
"coef": 12,
"moyenne": "12.00"
}
},
"saes": {
"SAE11": {
"id": 2,
"coef": 16,
"moyenne": "~"
}
},
"ECTS": {
"acquis": 0,
"total": 12
}
},
"semestre": {
"etapes": [],
"date_debut": "2021-09-01",
"date_fin": "2022-08-31",
"annee_universitaire": "2021 - 2022",
"numero": 1,
"inscription": "",
"groupes": [],
"absences": {
"injustifie": 1,
"total": 2
},
"ECTS": {
"acquis": 0,
"total": 30
},
"notes": {
"value": "10.60",
"min": "02.40",
"moy": "11.05",
"max": "17.40"
},
"rang": {
"value": "10",
"total": 16
}
}
}
}
]
```
* **`jury`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/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
```
### 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.
* **`moduleimpls`**
* **Méthode:** GET
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/formations/moduleimpl/<int:moduleimpl_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formations/moduleimpl/1`
* **Résultat:** Retourne la liste des moduleimpl
* **Exemple de résultat:**
```
XXX A COMPLETER
```
* **`moduleimpls_sem`**
* **Méthode:** GET
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/formations/moduleimpl/formsemestre/<int:formsemestre_id>/liste`
* **Exemple d'utilisation:** `/ScoDoc/api/formations/moduleimpl/formsemestre/1/liste`
* **Résultat:** Retourne la liste des moduleimpl d'un semestre
* **Exemple de résultat:**
```
[
{
"id": 1,
"formsemestre_id": 1,
"computation_expr": null,
"module_id": 1,
"responsable_id": 2,
"module": {
"heures_tp": 0,
"code_apogee": "",
"titre": "Initiation aux réseaux informatiques",
"coefficient": 1,
"module_type": 2,
"id": 1,
"ects": null,
"abbrev": "Init aux réseaux informatiques",
"ue_id": 1,
"code": "R101",
"formation_id": 1,
"heures_cours": 0,
"matiere_id": 1,
"heures_td": 0,
"semestre_id": 1,
"numero": 10,
"module_id": 1
},
"moduleimpl_id": 1,
"ens": []
}
]
```
### 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.
* **`partition`**
* **Méthode: GET**
* **Paramètres:** `formsemestre_id`
* **Routes:** `/ScoDoc/api/partitions/<int:formsemestre_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/48`
* **Résultat:** La liste de toutes les partitions d'un formsemestre.
* **Exemple de résultat:**
```
[
{
"partition_id": 2,
"id": 2,
"formsemestre_id": 1,
"partition_name": "TD",
"numero": 1,
"bul_show_rank": false,
"show_in_lists": true
},
{
"partition_id": 1,
"id": 1,
"formsemestre_id": 1,
"partition_name": null,
"numero": 0,
"bul_show_rank": false,
"show_in_lists": true
}
]
```
* **`etud_in_group`**
* **Méthode: GET**
* **Paramètres:** `group_id`, `etat`
* **Routes:** `/partitions/groups/<int:group_id>` ou `/partitions/groups/<int:group_id>/etat/<string:etat>`
* **Exemple d'utilisation:** `/ScoDoc/api/partitions/groups/1`
* **Résultat:** La liste de toutes les partitions d'un formsemestre.
* **Exemple de résultat:**
```
[
{
"etudid": 10,
"id": 10,
"dept_id": 1,
"nom": "BOUTET",
"prenom": "Marguerite",
"nom_usuel": "",
"civilite": "F",
"date_naissance": null,
"lieu_naissance": null,
"dept_naissance": null,
"nationalite": null,
"statut": null,
"boursier": null,
"photo_filename": null,
"code_nip": "10",
"code_ine": "10",
"scodoc7_id": null,
"email": "MARGUERITE.BOUTET@example.com",
"emailperso": null,
"domicile": null,
"codepostaldomicile": null,
"villedomicile": null,
"paysdomicile": null,
"telephone": null,
"telephonemobile": null,
"fax": null,
"typeadresse": "domicile",
"description": null,
"group_id": 1,
"etat": "I",
"civilite_str": "Mme",
"nom_disp": "BOUTET",
"nomprenom": "Mme Marguerite BOUTET",
"ne": "e",
"email_default": "MARGUERITE.BOUTET@example.com"
}
]
```
* **`set_groups`**
* **Méthode:** POST
* **Paramètres:** `partition_id`, `groups_lists`, `groups_to_delete`, `groups_to_create`
* **Routes:** `/partitions/set_groups/partition/<int:partition_id>/groups/<string:groups_id>/delete/<string:groups_to_delete>/create/<string:groups_to_create>`
* **Exemple d'utilisation:** `/ScoDoc/api/partitions/set_groups/partition/1/groups/"A COMPLETER"/delete/"A COMPLETER"/create/"A COMPLETER"`
* **Résultat:** Set les groups.
### Bulletins de notes
* **`evaluations`**
* **Méthode:** GET
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/evaluations/<int:moduleimpl_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/1`
* **Résultat:** Retourne la liste des évaluations à partir de l'id d'un moduleimpl
* **Exemple de résultat:**
```
[
{
"moduleimpl_id": 1,
"jour": "20/04/2022",
"heure_debut": "08h00",
"description": "eval1",
"coefficient": 1,
"publish_incomplete": false,
"numero": 0,
"id": 1,
"heure_fin": "09h00",
"note_max": 20,
"visibulletin": true,
"evaluation_type": 0,
"evaluation_id": 1,
"jouriso": "2022-04-20",
"duree": "1h",
"descrheure": " de 08h00 à 09h00",
"matin": 1,
"apresmidi": 0
}
]
```
* **`evaluation_notes`**
* **Méthode**: GET
* **Paramètres**: `evaluation_id`
* **Routes:** `/evaluations/eval_notes/<int:evaluation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_notes/1`
* **Résultat:** Retourne la liste des notes à partir de l'id d'une évaluation donnée
* **Exemple de résultat:**
```
{
"1": {
"id": 1,
"etudid": 10,
"evaluation_id": 1,
"value": 15,
"comment": "",
"date": "Wed, 20 Apr 2022 06:49:05 GMT",
"uid": 2
},
"2": {
"id": 2,
"etudid": 1,
"evaluation_id": 1,
"value": 12,
"comment": "",
"date": "Wed, 20 Apr 2022 06:49:06 GMT",
"uid": 2
}
}
```
### 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/<int:etudid>` ou `/absences/nip/<int:nip>` ou `/absences/ine/<int:ine>`
* **Exemple d'utilisation:** `/ScoDoc/api/absences/ine/1`
* **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": "",
"begin": "2022-04-15 08:00:00",
"end": "2022-04-15 11:59:59"
},
{
"jour": "2022-04-15",
"matin": false,
"estabs": true,
"estjust": false,
"description": "",
"begin": "2022-04-15 12:00:00",
"end": "2022-04-15 17:59:59"
}
]
```
* **`absences_just`**
* **Méthode:** GET
* **Paramètres:** `etudid`, `nip`, `ine`
* **Routes:** `/absences/etudid/<int:etudid>/just` ou `/absences/nip/<int:nip>/just` ou `/absences/ine/<int:ine>/just`
* **Exemple d'utilisation:** `/ScoDoc/api/absences/ine/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": "",
"begin": "2022-04-15 08:00:00",
"end": "2022-04-15 11:59:59"
},
{
"jour": "2022-04-15",
"matin": false,
"estabs": true,
"estjust": true,
"description": "",
"begin": "2022-04-15 12:00:00",
"end": "2022-04-15 17:59:59"
}
]
```
* **`abs_groupe_etat`**
* **Méthode:** GET
* **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html`
* **Routes:** `/absences/abs_group_etat/<int:group_id>` ou `/absences/abs_group_etat/group_id/<in:group_id>/date_debut/<date:date_debut>/date_fin/<date:date_fin>`
* **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/1`
* **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates.
* **Exemple de résultat:**
```
XXX A COMPLETER
```
### Jury
* **`jury_preparation`**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Routes:** `/jury/formsemestre/<int:formsemestre_id>/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/<int:formsemestre_id>/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
```
### Logos
* **`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`
* **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`**
* **Méthode:** GET
* **Paramètres :** Aucun
* **Route:** `/ScoDoc/api/logos/<string:nom>`
* **Exemple d'utilisation :** `/ScoDoc/api/logos/header`
* **Résultat :** l'image (format png ou jpg)
* **`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`
* **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`**
* **Méthode:** GET
* **Paramètres :** Aucun
* **Route:** `/ScoDoc/api/departements/<string:dept>/logos/<string:nom>`
* **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/logos/header`
* **Résultat :** l'image (format png ou jpg)
### En savoir plus
Voir exemples d'utilisation de l'API en Python, dans `tests/api/`.
## 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.