jmplace/DocScoDoc
1
0
Fork 0
forked from ScoDoc/DocScoDoc
Code Issues Pull Requests Projects Releases Wiki Activity

merge origin master

Browse Source
This commit is contained in:
leonard_montalbano 2022-04-26 16:57:22 +02:00
commit 1b61d49d63
1 changed files with 350 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

569
docs/ScoDoc9API.md
View File

@ -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. 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. La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification.
@ -24,51 +24,47 @@ 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`. L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`.
## Configuration de ScoDoc pour utiliser l'API # Fonctions de l'API ScoDoc 7 portées en ScoDoc 9
Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats. L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md)
En général, il est recommandé de créer un rôle, de lui attribuer les permissions Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les
que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle. 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 ligne de commande, cela peut se faire comme suit (voir détail des commandes Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.
[sur le guide de configuration](GuideConfig.md)).
``` - `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/<int:etudid>`)
# se connecter comme utilisateur scodoc - `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`)
su - scodoc - `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/<int: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/<int:etudid>`)
- `groups_view` (deviendra `groups`)
# Créer un rôle Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est
flask create-role LecteurAPI à dire `https://votre.site.fr/ScoDoc/<dept>/Scolarite/`, et répondent en GET et
# Lui donner les droits nécessaires: ici APIView en POST.
flask edit-role LecteurAPI -a APIView
# Créer un nouvel utilisateur avec ce rôle: Note:
flask user-create lecteur_api LecteurAPI @all - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.
# Ou bien, si on veut utiliser un compte existant: # Fonctions d'API ScoDoc 9 (work in progress)
# 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) 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 La documentation ci-dessous concerne la **future** version De ScoDoc.
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 Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
#### Authentification L'ensemble des routes sont visible via la commande suivante : ``flask routes | grep /ScoDoc/api``
### Authentification
Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il
vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant
@ -93,7 +89,7 @@ La réponse doit ressembler à ceci:
Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple
complet en python d'interrogation de l'API. 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 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 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. que la requête a été traitée avec succès.
@ -111,159 +107,315 @@ 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. * [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`** * **`departements`**
* **Méthode:** GET * **Méthode:** GET
* **Routes:** `/departements` * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessibles à l'utilisateur courant), `format` (json, xml)
* **Exemple d'utilisation:** `/api/departements` * **Routes:** `/ScoDoc/api/departements`
* **Exemple d'utilisation:** `/ScoDoc/api/departements`
* **Résultat:** Liste des id de départements. * **Résultat:** Liste des id de départements.
* **Exemple de résultat:** `[1, 2, 3, ...]` * **Exemple de résultat:** `[id_1, id_2, id_3, ...]`
* **`liste_etudiants`** * **`liste_etudiants`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `dept`, `formsemestre_id` * **Paramètres:** `dept`, `formsemestre_id`
* **Routes:** `/departements/<string:dept>/etudiants/liste` ou `/api/departements/<string:dept>/etudiants/liste/<int:formsemestre_id>` * **Routes:** `/ScoDoc/api/departements/<string:dept>/etudiants/liste/<int:formsemestre_id>` (_`semestre` étant un paramètre optionnel_)
* **Exemple d'utilisation:** `/api/departements/MMI/etudiants/liste` * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/etudiants/liste`
* **Résultat:** liste des étudiants d'un département, par défaut, ou d'un semestre si renseigné * **Résultat:** Liste des étudiants d'un département - semestre actuel par défaut.
* **`liste_semestres_courant`** XXX à revoir * **`liste_semestres_actifs`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `dept` * **Paramètres:** `dept`
* **Routes:** `/departements/<string:dept>/semestres_courants` * **Routes:** `/ScoDoc/api/departements/<string:dept>/semestres_actifs`
* **Exemple d'utilisation:** `/api/departements/MMI/semestres_courants` * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/semestres_actifs`
* **Résultat:** Liste des semestres actifs d'un département donné. (_réponse sous format json_) * **Résultat:** Liste des semestres actifs d'un département donné. (_réponse sous format json_)
* **`referentiel_competences`** * **`referenciel_competences`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `dept`, `formation_id` * **Paramètres:** `dept`, `formation` (_`formation` étant un id de formation, un programme pédagogique_)
* **Routes:** `/departements/<string:dept>/formations/<int:formation_id>/referentiel_competences` * **Routes:** `/ScoDoc/api/departements/<string:dept>/formations/<int:formation>/referentiel_competences`
* **Exemple d'utilisation:** `api/departements/MMI/formations/1/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 (json). (_pas toujours présent_) * **Résultat:** Le référentiel de compétences d'une formation donnée au format json. (_pas toujours présent_)
* XXX obtenir la liste des référentiels
* **`semestre_index`** ## Etudiants
* **`etud_dept`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `dept`, `formsemestre_id` * **Paramètres:** `code_nip`
* **Routes:** `/departements/<string:dept>/formsemestre/<string:formsemestre_id>/programme` * **Routes:** `/ScoDoc/api/etud_dept/<int:code_nip>`
* **Exemple d'utilisation:** `api/departements/MMI/formsemestre/1/programme` * **Exemple d'utilisation:** `/ScoDoc/api/etud_dept/123`
* **Résultat:** Retourne la liste des Ues, ressources et SAE d'un semestre (json). * **Résultat:** Liste des étudiants avec le code NIP donné tirée par ordre d'inscription décroissant.
### Etudiants
* **`etudiants_courant`**
* **Méthode:** GET
* **Routes:** `/etudiants/courant`
* **Exemple d'utilisation:** `/api/etudiants/courant`
* **Résultat:** Retourne la liste des étudiants courant (json).
* **Exemple de résultat:** * **Exemple de résultat:**
``` ```
{ [
{ {
"civilite": "X", exist: true,
"code_ine": null, dept: "GEII",
"code_nip": null, id: 987,
"date_naissance": null, dept_id: 3
"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`** * **`etudiant`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `etudid`, `nip`, `ine` * **Paramètres:** `etudid`
* **Routes:** `/etudiant/etudid/<int:etudid>` ou `/etudiant/nip/<int:nip>` ou `/etudiant/ine/<int:ine>` * **Routes:** `/ScoDoc/api/etudiant/<int:etudid>`
* **Exemple d'utilisation:** `/api/etudiant/nip/1` * **Exemple d'utilisation:** `/ScoDoc/api/etudiant/987`
* **Résultat:** Retourne les informations de l'étudiant correspondant à l'id passé en paramètres. (json) * **Résultat:** Un dictionnaire avec les informations de l'étudiant correspondant à l'id passé en paramètres.
* **Exemple de résultat:** * **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"
}
``` ```
{
"nom": "Mutis",
* **`etudiant_formsemestres`** "sexe": "M.",
* **Méthode:** GET "email": "alvaro.mutis@example.com",
* **Paramètres:** `etudid`, `nip`, `ine` "prenom": "ALVARO",
* **Routes:** : `/etudiant/etudid/<int:etudid>/formsemestres` ou `/etudiant/nip/<int:nip>/formsemestres` ou `/etudiant/ine/<int:ine>/formsemestres` "nomprenom": "M. Alvaro MUTIS",
* **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres` "insemestre": [
* **Résultat:** Retourne la liste des semestres qu'un étudiant a suivis, triés par ordre chronologique. (json) {
"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": ""
}
```
* **`etudiant_bulletin_semestre`** * **`etudiant_bulletin_semestre`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` * **Paramètres:** `etudid`, `sem_id`
* **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` * **Routes:** `/ScoDoc/api/etudiant/<int:etudid>/semestre/<int:sem_id>/bulletin`
* **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin` * **Exemple d'utilisation:** `/ScoDoc/api/etudiant/987/semestre/12/bulletin`
* **Résultat:** Retourne le bulletin d'un étudiant en fonction de son id et d'un semestre donné. (json) * **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/<int:formsemestre_id>/departements/<string:dept>/etudiant/nip|id|ine/{NIP}|{etudid}|numScodoc}/bulletin?format=<string:format>&version=<string: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&apos;entreprises",
"effectif": {
"value": 51
},
"titre": "Initiation aux r\u00e9seaux d&apos;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 &amp;amp; Culture",
"id": "UE23716"
}
],
"situation": "Inscrit le 2015-09-02. D\u00e9cision jury: Valid\u00e9. UE acquises: UE11, UE12. Autoris\u00e9 \u00e0 s&apos;inscrire en S2."
}
```
* **`etudiant_photo`**
* **Méthode:** GET
* **Paramètres:** `etudid`, `small`
* **Routes:** `/ScoDoc/api/etudiant/<int:etudid>/photo` **OU** `/ScoDoc/api/etudiant/<int:etudid>/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.
* **`etudiant_groups`** * **`etudiant_groups`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` * **Paramètres:** `etudid`, `formsemestre_id`
* **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` * **Routes:** `/ScoDoc/api/etudiant/<int:etudid>/semestre/<int:formsemestre_id>/groups`
* **Exemple d'utilisation:** `/etudiant/nip/1/semestre/1/groups` * **Exemple d'utilisation:** `/ScoDoc/api/etudiants/123/semestre/INFO-DUT-FI-S1-2014/groups`
* **Résultat:** Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json) * **Résultat:** Liste des groupes auxquels appartient l'étudiant dans le semestre indiqué.
* **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"
},
...
]
```
```
{
"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"
}
]
}
```
@ -271,8 +423,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
* **`formations`** * **`formations`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formation_id` (_optionnel, si absent, liste toutes les formations_) * **Paramètres:** `formation_id` (_optionnel, si absent, liste toutes les formations_)
* **Routes:** `/api/formations` **ou** `/api/formations/<int:formation_id>` * **Routes:** `/ScoDoc/api/formations` **ou** `/ScoDoc/api/formations/<int:formation_id>`
* **Exemple d'utilisation:** `/api/formations` **ou** `/api/formations/1` * **Exemple d'utilisation:** `/ScoDoc/api/formations` **ou** `/ScoDoc/api/formations/1`
* **Résultat:** Liste des formations. * **Résultat:** Liste des formations.
* **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]` * **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]`
* TODO: détailler le contenu publié * TODO: détailler le contenu publié
@ -282,8 +434,8 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
* **`formation_export`** * **`formation_export`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formation_id`, `export_ids` (_par défaut "faux"_) * **Paramètres:** `formation_id`, `export_ids` (_par défaut "faux"_)
* **Routes:** `/api/formations/formation_export/<int:formation_id>` * **Routes:** `/ScoDoc/api/formations/formation_export/<int:formation_id>?format=<string:format>&export_ids=<int:export_ids>`
* **Exemple d'utilisation:** `/api/formations/formation_export/596` **ou** `/api/formations/formation_export/596?format=xml&export_ids=1` * **Exemple d'utilisation:** `/ScoDoc/api/formations/formation_export/596` **ou** `/ScoDoc/api/formations/formation_export/596?format=xml&export_ids=1`
* **Résultat:** La formation, avec UE, matières, modules (_un arbre_). * **Résultat:** La formation, avec UE, matières, modules (_un arbre_).
* **Exemple de résultat:** * **Exemple de résultat:**
``` ```
@ -299,25 +451,25 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
} }
``` ```
### UE ## UE
* **`UEs`** * **`UEs`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `dept`, `̀semestre` * **Paramètres:** `dept`, `̀semestre`
* **Routes:** `/api/departements/<str:dept>/formations/programme/<str:semestre>` * **Routes:** `/ScoDoc/api/departements/<string:dept>/formations/programme/<string:semestre>`
* **Exemple d'utilisation:** `̀/api/departements/MMI/formations/programme/INFO-DUT-FI-S1-2014` * **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 * **Résultat:** Liste des UEs, ressources et SAE d'un semestre
### 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`. 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`** * **`formsemestre`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id` ou `etape_apo`, `format`(json ou xml) * **Paramètres:** `formsemestre_id` ou `etape_apo`, `format`(json ou xml)
* **Routes:** `/api/formations/formsemestre/<int:formsemestre_id>`, `/api/formsemestre/apo/<etape_apo>` * **Routes:** `/ScoDoc/api/formations/formsemestre/<int:formsemestre_id>`, `/ScoDoc/api/formsemestre/apo/<etape_apo>`
* **Exemple d'utilisation:** `/api/formations/formsemestre/12` * **Exemple d'utilisation:** `/ScoDoc/api/formations/formsemestre/12`
* **Résultat:** Informations sur le(s) formsemestre(s). * **Résultat:** Informations sur le(s) formsemestre(s).
* **Exemple de résultat:** * **Exemple de résultat:**
``` ```
@ -340,7 +492,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 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 (presque) unique une session dans un établissement, ce qui est utile
notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois
@ -361,14 +513,14 @@ informations suivantes:
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI) **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. 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. On peut récupérer soit un module par son id, soit la listes des modules d'un semestre.
* **`moduleimpl`** * **`moduleimpl`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres**: `formsemestre_id` ou `moduleimpl_id` * **Paramètres**: `formsemestre_id` ou `moduleimpl_id`
* **Routes:** `/api/formations/moduleimpl/<int:moduleimpl_id>` **ou** `/api/formations/moduleimpl/<int:moduleimpl_id>/formsemestre/<int:formsemestre_id>` * **Routes:** `/ScoDoc/api/formations/moduleimpl/<int:moduleimpl_id>` **ou** `/ScoDoc/api/formations/moduleimpl/<int:moduleimpl_id>/formsemestre/<int:formsemestre_id>`
* **Résultat:** liste de moduleimpl * **Résultat:** liste de moduleimpl
* **Exemple de résultat:** * **Exemple de résultat:**
TODO TODO
@ -377,7 +529,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 L'ensemble des étudiants d'un semestre peut être réparti selon une ou
plusieurs partitions (types de groupes). Chaque partition est constituée plusieurs partitions (types de groupes). Chaque partition est constituée
@ -386,8 +538,8 @@ d'un nombre quelconque de groupes d'étudiants.
* **`partition`** * **`partition`**
* **Méthode: GET** * **Méthode: GET**
* **Paramètres:** `formsemestre_id` * **Paramètres:** `formsemestre_id`
* **Routes:** `/api/partitions/<int:formsemestre_id>` * **Routes:** `/ScoDoc/api/partitions/<int:formsemestre_id>`
* **Exemple d'utilisation:** `/api/partition/48` * **Exemple d'utilisation:** `/ScoDoc/api/partition/48`
* **Résultat:** La liste de toutes les partitions d'un formsemestre. * **Résultat:** La liste de toutes les partitions d'un formsemestre.
* **Exemple de résultat:** * **Exemple de résultat:**
``` ```
@ -442,10 +594,10 @@ d'un nombre quelconque de groupes d'étudiants.
* **`groups`** * **`groups`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I` * **Paramètres:** `formsemestre_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I`
* **Routes:** `api/partitions/formsemestre/<int:formsemestre_id>/groups/group_ids?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:** `api/partitions/formsemestre/213/groups/123?with_codes=1` * **Exemple d'utilisation:** `/ScoDoc/api/partitions/formsemestre/213/groups/123?with_codes=True`
* **Résultat:** Liste des étudiants dans un groupe. * **Résultat:** Liste des étudiants dans un groupe.
* **Exemple de résultat au format XML:** (_avec `with_codes=1`_) * **Exemple de résultat au format XML:** (_avec `with_codes=True`_)
``` ```
<group_list origin="" caption="soit 21 étudiants inscrits et 2 démissionaires." id="gt_711068"> <group_list origin="" caption="soit 21 étudiants inscrits et 2 démissionaires." id="gt_711068">
@ -478,7 +630,7 @@ d'un nombre quelconque de groupes d'étudiants.
"etat":"I", "etat":"I",
"emailperso":null, "emailperso":null,
"prenom":"Dalil", "prenom":"Dalil",
"nom_disp":"CLINTO", "nom_disp":"CLINTO",?
"email":"xxx@example.com", "email":"xxx@example.com",
"62029":"A", "62029":"A",
"62032":null, "62032":null,
@ -504,19 +656,19 @@ d'un nombre quelconque de groupes d'étudiants.
* **`set_groups`** * **`set_groups`**
* **Méthode:** POST * **Méthode:** POST
* **Paramètres:** `partition_id`, `groups`, `groups_to_delete`, `groups_to_create` * **Paramètres:** `partition_id`, `groups`, `groups_to_delete`, `groups_to_create`
* **Routes:** `/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>` * **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:** `/api/partitions/set_groups?partition_id=65&groups=77&groups_to_delete=8&groups_to_create=4` * **Exemple d'utilisation:** `/ScoDoc/api/partitions/set_groups?partition_id=65&groups=77&groups_to_delete=8&groups_to_create=4`
* **Résultat:** Set les groups. * **Résultat:** Set les groups.
TODO: à changer, passer les paramètres dans le corps de la requête TODO: à changer, passer les paramètres dans le corps de la requête
### Bulletins de notes ## Bulletins de notes
* **`evaluations`** * **`evaluations`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `moduleimpl_id` * **Paramètres:** `moduleimpl_id`
* **Routes:** `/api/evaluations/<int:moduleimpl_id>` * **Routes:** `/ScoDoc/api/evaluations/<int:moduleimpl_id>`
* **Exemple d'utilisation:** `/api/evaluations/54` * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/54`
* **Résultat:** Liste des évaluations à partir de l'id d'un moduleimpl. * **Résultat:** Liste des évaluations à partir de l'id d'un moduleimpl.
* **Exemple de résultat:** `[eval_1, eval_2, eval_3, ...]` * **Exemple de résultat:** `[eval_1, eval_2, eval_3, ...]`
@ -524,8 +676,8 @@ d'un nombre quelconque de groupes d'étudiants.
* **`evaluation_notes`** * **`evaluation_notes`**
* **Méthode**: GET * **Méthode**: GET
* **Paramètres**: `evaluation_id` * **Paramètres**: `evaluation_id`
* **Routes:** `/api/evaluations/eval_notes/<int:evaluation_id>` * **Routes:** `/ScoDoc/api/evaluations/eval_notes/<int:evaluation_id>`
* **Exemple d'utilisation:** `/api/evaluations/eval_notes/24` * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_notes/24`
* **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée. * **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée.
* **Exemple de résultat:** * **Exemple de résultat:**
``` ```
@ -543,21 +695,21 @@ d'un nombre quelconque de groupes d'étudiants.
* **`evaluation_set_notes`** * **`evaluation_set_notes`**
* **Méthode:** POST * **Méthode:** POST
* **Paramètres:** `eval_id`, `etudid`, `note` * **Paramètres:** `eval_id`, `etudid`, `note`
* **Routes:** `/api/evaluations/eval_set_notes?eval_id=<int:eval_id> etudid=<int etudid>&note=<int:note>` * **Routes:** `/ScoDoc/api/evaluations/eval_set_notes?eval_id=<int:eval_id>&etudid=<int:etudid>&note=<int:note>`
* **Exemple d'utilisation:** `/api/evaluations/eval_set_notes?eval_id=6 etudid=456&note=15` * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/eval_set_notes?eval_id=6&etudid=456&note=15`
* **Résultat:** Set les notes d'une évaluation pour un étudiant donné. * **Résultat:** Set les notes d'une évaluation pour un étudiant donné.
TODO vérifier et passer les valeurs dans le corps. 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. **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`** * **`absences`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `etudid`, `abs_just_only, format`, `abs_just_only` (_spécifie si on veut les absences justifiées ou non_). * **Paramètres:** `etudid`, `abs_just_only, format`, `abs_just_only` (_spécifie si on veut les absences justifiées ou non_).
* **Routes:** `/api/absences/<int:etudid>` * **Routes:** `/ScoDoc/api/absences/<int:etudid>`
* **Exemple d'utilisation:** `/api/absences/54` * **Exemple d'utilisation:** `/ScoDoc/api/absences/54`
* **Résultat:** Liste des absences d'un étudiant donné. * **Résultat:** Liste des absences d'un étudiant donné.
* **Exemple de résultat:** * **Exemple de résultat:**
```{jour: "2021-02-10", ampm: "0", description: "M2202", }``` (_**ampm** vaut 1 le matin et 0 l'après-midi_). ```{jour: "2021-02-10", ampm: "0", description: "M2202", }``` (_**ampm** vaut 1 le matin et 0 l'après-midi_).
@ -590,8 +742,8 @@ d'un nombre quelconque de groupes d'étudiants.
* **`abs_groupe_etat`** * **`abs_groupe_etat`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html` * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html`
* **Routes:** `/api/absences/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin` * **Routes:** `/ScoDoc/api/absences/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin`
* **Exemple d'utilisation:** `/api/absences/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30` * **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30`
* **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates. * **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates.
* **Exemple de résultat:** si `format="json"` cela donne: * **Exemple de résultat:** si `format="json"` cela donne:
``` ```
@ -609,13 +761,13 @@ d'un nombre quelconque de groupes d'étudiants.
] ]
``` ```
### Logos ## Logos
* **`liste des logos globaux`** * **`liste des logos globaux`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `format` (json, xml), json par défaut * **Paramètres:** `format` (json, xml), json par défaut
* **Route :** `/api/logos` * **Route :** `/ScoDoc/api/logos`
* **Exemple d'utilisation :** `/api/logos?format=xml` * **Exemple d'utilisation :** `/ScoDoc/api/logos?format=xml`
* **Résultat :** Liste des logos définis pour le site scodoc. * **Résultat :** Liste des logos définis pour le site scodoc.
* **Exemple de résultat:** `['header', 'footer', 'custom']` * **Exemple de résultat:** `['header', 'footer', 'custom']`
@ -623,16 +775,16 @@ d'un nombre quelconque de groupes d'étudiants.
* **`récupération d'un logo global`** * **`récupération d'un logo global`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres :** Aucun * **Paramètres :** Aucun
* **Route:** `/api/logos/<str:nom>` * **Route:** `/ScoDoc/api/logos/<string:nom>`
* **Exemple d'utilisation :** `/api/logos/header` * **Exemple d'utilisation :** `/ScoDoc/api/logos/header`
* **Résultat :** l'image (format png ou jpg) * **Résultat :** l'image (format png ou jpg)
* **`logo d'un département`** * **`logo d'un département`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `format` (json, xml) * **Paramètres:** `format` (json, xml)
* **Route :** `/api/departements/<str:dept>/logos` * **Route :** `/ScoDoc/api/departements/<string:dept>/logos`
* **Exemple d'utilisation :** `/api/MMI/logos` * **Exemple d'utilisation :** `/ScoDoc/api/MMI/logos`
* **Résultat :** Liste des logos définis pour le département visé. * **Résultat :** Liste des logos définis pour le département visé.
* **Exemple de résultat:** `['footer', 'signature', 'universite']` * **Exemple de résultat:** `['footer', 'signature', 'universite']`
@ -640,38 +792,11 @@ d'un nombre quelconque de groupes d'étudiants.
* **`récupération d'un logo global`** * **`récupération d'un logo global`**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres :** Aucun * **Paramètres :** Aucun
* **Route:** `/api/departements/<str:dept>/logos/<str:nom>` * **Route:** `/ScoDoc/api/departements/<string:dept>/logos/<string:nom>`
* **Exemple d'utilisation:** `/api/departements/MMI/logos/header` * **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/logos/header`
* **Résultat :** l'image (format png ou jpg) * **Résultat :** l'image (format png ou jpg)
### En savoir plus
## En savoir plus
Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. 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.