64 KiB
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, ou sur le canal #API
du Discord développeurs.
L'API fournit des données JSON, sauf exception (bulletins PDF par exemple).
Les objets ScoDoc manipulables sont identifiés par des id numériques.
- 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)
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.
Les droits à accorder dépendent des fonctionnalités nécessaires. la permission ScoView
est généralement suffisante car elle permet toutes les consultations.
Cependant si, par l'API, on veut effectuer des opérations de modification ou encore consulter les comptes utilisateurs, d'autres droits (ScoChangeGroups
, ScoUsersView
, ScoSuperAdmin
, ...) peuvent être requis.
La consultation du tableau récapitulatif ou la ligne permission
de chaque entrée vous donnera la permission requise pour chaque opération.
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).
# se connecter comme utilisateur scodoc
su - scodoc
# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici ScoView
flask edit-role LecteurAPI -a ScoView
# 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
...
Si vous êtes intéressé par le développement, voir la section sur les tests unitaires de l'API.
Essais avec HTTPie
HTTPie est un client universel livre et gratuit très commode, disponible pour Windows, Linux, en ligne de commande ou interface graphique.
Exemple d'utilisation en ligne de commande et interroger votre ScoDoc pour obtenir la liste des départements:
http -a USER:PASSWORD POST 'http://localhost:5000/ScoDoc/api/tokens'
Qui affiche:
HTTP/1.1 200 OK
Content-Length: 50
Content-Type: application/json
Date: Thu, 05 May 2022 04:29:33 GMT
{
"token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
}
(remplacer USER:PASSWORD par les identifiants de votre utilisateur et adapter l'URL qui est ici celle d'un client local sur le serveur de test).
Avec ce jeton (token), on peut interroger le serveur:
http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
qui affiche par exemple:
HTTP/1.1 200 OK
Content-Length: 151
Content-Type: application/json
Date: Thu, 05 May 2022 05:21:33 GMT
[
{
"acronym": "TAPI",
"date_creation": "Wed, 04 May 2022 21:09:25 GMT",
"description": null,
"id": 1,
"visible": true
}
]
Fonctions d'API ScoDoc 9
La documentation ci-dessous concerne la nouvelle API, disponible à partir de la version de ScoDoc 9.3.25.
Accès à l'API REST
L'API est accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
(et aussi https://scodoc.monsite.tld/ScoDoc/api/<dept_acronyme>/fonction
pour un
accès avec des droits restreints au département indiqué).
Authentification
Lors de votre authentification (connexion 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, voir plus haut pour la même chose avec la commande http
):
curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens
où 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 le serveur ScoDoc.
- 200 : OK.
- 401 : Authentification nécessaire. (jeton non précisé ou invalide)
- 403 : Action non autorisée pour l'utilisateur associé au jeton.
- 404 : Adresse incorrecte, paramètre manquant ou invalide, ou objet inexistant.
- 500 : Erreur inconnue côté serveur.
Règles générales
- une route s'écrit comme une suite de noms et d'identifiants;
- les noms token, departement, formation, formsemestre, groupe, etudiant, bulletin, absence, logo, programme, évaluation, resultat, decision désignent des types d'objets;
- les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query, create, delete, edit, order sont des actions;
- les noms restants (ids, courants, long, ...) sont des options, les autres noms sont des options ou des actions;
- le dernier nom apparaissant sur une route donne le type d'objet renvoyé. Ce
nom peut apparaître au singulier ou au pluriel.
- au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404;
- au pluriel une collection d'objets est renvoyée, si aucun objet n'est trouvé, retourne une collection vide.
- un type d'objet au singulier est généralement suivi immédiatement de son identifiant (unique). Exception: pour un étudiant, on peut également utiliser le NIP ou l'INE (qui ne sont pas uniques dans la base car un étudiant de même INE/NIP peut passer par plusieurs départements).
Référence
La carte syntaxique vous permet de retrouver une entrée à
partir de sa syntaxe (le ?
amène sur la documentation associée).
Le tableau récapitulatif vous permet de rechercher une entrée à partir du résultat attendu.
Carte syntaxique
Tableau récapitulatif des entrées de l'API
Ce tableau est trié selon le type des informations renvoyées:
- un nom simple représente un seul objet de ce type;
- suivi de
+
désigne une forme 'longue' d'objet de ce type; - suivi de
*
désigne une liste de 0, 1 ou plusieurs objets du type; - suivi de
#
désigne une liste d'entiers (les ids des objets du type); - suivi de
:
puis d'un nom en majuscule indique une requête (POST) qui modifie les données de ScoDoc.
Retour | Remarque | Méthode | Navigation | Permission |
---|---|---|---|---|
departement*** ** |
tous les depts | GET | departements | |
departement**# ** |
tous les ids des depts | GET | departements-ids | ScoView |
departement | recherche par id | GET | departement | ScoView |
departement | recherche par acronyme | GET | departement | ScoView |
departement:CREATE | création d'un département | POST | departement-create | ScoSuperAdmin |
departement:EDIT | modification d'un département | POST | departement-edit | ScoSuperAdmin |
departementDELETE | suppression d'un département | POST | departement-delete | ScoSuperAdmin |
formation*** ** |
toutes les formations accessibles | GET | formations | ScoView |
formation**# ** |
ids des formations accessibles | GET | formations-ids | ScoView |
formation | une formation | GET | formation | ScoView |
export | GET | formation-export | ScoView | |
export**+ ** |
GET | formation-export_with_ids | ScoView | |
referentiel_competences | GET | formation-referenciel_competences | ScoView | |
formsemestre**# ** |
GET | departement-formsemestres_ids | ScoView | |
formsemestre*** ** |
GET | departement-formsemestres_courants | ScoView | |
formsemestre*** ** |
GET | formsemestre-query | ScoView | |
formsemestre*** ** |
GET | etudiant-formsemestres | ScoView | |
formsemestre | GET | formsemestre | ScoView | |
moduleimpl | GET | moduleimpl | ScoView | |
partition*** ** |
GET | formsemestre-partitions | ScoView | |
partition | GET | partition | ScoView | |
partition:CREATE | POST | formsemestre-partition-create | ScoEtudChangeGroups | |
partition:EDIT | POST | partition-edit | ScoEtudChangeGroups | |
partition:ACTION | POST | formsemestre-partitions-order | ScoEtudChangeGroups | |
partition:DELETE | POST | partition-delete | ScoEtudChangeGroups | |
partition:ACTION | POST | partition-remove_etudiant | ScoEtudChangeGroups | |
group:CREATE | POST | partition-group-create | ScoEtudChangeGroups | |
group:EDIT | POST | group-edit | ScoEtudChangeGroups | |
group:ACTION | POST | partition-groups-order | ScoEtudChangeGroups | |
group:DELETE | POST | group-delete | ScoEtudChangeGroups | |
group* | GET | etudiant-formsemestre-groups | ScoView | |
group:ACTION | POST | group-set_etudiant | ScoEtudChangeGroups | |
group:ACTION | POST | group-remove_etudiant | ScoEtudChangeGroups | |
etudiant*** ** |
recherche par etudid, nip ou ine | GET | etudiants-clef | ScoView |
etudiant*** ** |
les étudiants actuels | GET | etudiants-courant | ScoView |
etudiant*** ** |
GET | departement-etudiants | ScoView | |
etudiant*** ** |
GET | formsemestre-etudiants | ScoView | |
etudiant*** ** |
GET | formsemestre-etudiants-query | ScoView | |
etudiant*** ** |
GET | group-etudiants-query | ScoView | |
etudiant*** ** |
GET | group-etudiants-query | ||
etudiant | GET | etudiant | ScoView | |
bulletin*** ** |
GET | formsemestre-bulletin | ScoView | |
bulletin | GET | etudiant-formsemestre-bulletin | ScoView | |
programme | GET | formsemestre-programme | ScoView | |
GET | formsemestre-etat_evals | ScoView | ||
GET | formsemestre-resultats | ScoView | ||
jury | GET | formsemestre-decisions_jury | ScoView | |
note* | GET | evaluation-notes | ScoView | |
logo*** ** |
GET | logos | ScoSuperAdmin | |
logo*** ** |
GET | departement-logos | ScoSuperAdmin | |
logo | GET | logo | ScoSuperAdmin | |
logo | GET | departement-logo | ScoSuperAdmin | |
user | GET | user | ScoUsView | |
user*** ** |
GET | users-query | ScoUsView | |
user:CREATE | POST | user-create | ScoUserAdmin | |
user:EDIT | POST | user-edit | ScoUserAdmin | |
user:PASSWORD | change le mot de passe d'un utilisateur | POST | user-password | ScoUserAdmin |
user:ACTION | POST | user-role-add | ScoUserAdmin | |
user:ACTION | POST | user-role-remove | ScoUserAdmin | |
permission*** ** |
GET | permissions | ScoUsView | |
role*** ** |
GET | roles | ScoUsView | |
role*** ** |
GET | role | ScoUsView | |
role:ACTION | POST | role-add_permission | ScoUserAdmin | |
role:ACTION | POST | role-remove_permission | ScoUserAdmin | |
role:CREATE | POST | role-create | ScoUserAdmin | |
role:EDIT | POST | role-edit | ScoUserAdmin | |
role:DELETE | POST | role-delete | ScoUserAdmin |
Note sur les exemples d'utilisation
Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-traitements non réalisés par l'API. Il n'est par exemple pas garanti que les clés des objets json sont triées:
- les clés sont triées
- les listes de plus de 2 éléments sont tronquées à 2 éléments, la fin de la liste étant représentée par la notation nn json '...'
- les dates (au format iso) sont systématiquement remplacées par une date fixe (la date de modification d'un mot de passe peut évidement être différente de sa date de création)
API Départements
Structure Département
attribut | type | commentaire |
---|---|---|
id | int | identifiant unique |
acronym | string | acronyme du département (fixe et unique) |
descripton | string | |
visible | bool | affiché ou non dans la page d'accueil |
date_creation | string | date ISO |
departements
- Méthode: GET
- Routes:
/departements
- Exemple d'utilisation:
/api/departements
- Résultat: Liste de tous les départements (visibles ou non).
- Exemple de résultat: departements.json
departements-ids
- Méthode: GET
- Permission:
ScoView
- Routes:
/departements_ids
- Résultat: Liste des id départements (visibles ou non).
- Exemple de résultat:
- Exemple de résultat: departements-ids.json
departement
- Méthode: GET
- Permission:
ScoView
- Routes:
/departement/id/<int:dept_id>
/departement/<string:dept>
- Résultat: Un département
- Exemple de résultat: departement.json
departement-create
- Méthode: POST
- Permission:
ScoSuperAdmin
- Paramètres: aucun
- Data:
{ "acronym": str, "visible":bool }
- Routes:
/departement/create
- Exemple d'utilisation:
/departement/create
{ "acronym": "QLIO", "visible": true }
- Résultat: Crée un nouveau département. L'acronyme du département (RT,
GEII, ...) doit être unique (il est d'usage de le mettre en majuscules, mais
ce n'est pas obligatoire). Le paramètre optionnel
visible
indique si le département est affiché sur la page d'accueil de ScoDoc. Notez qu'un département "invisible" peut quand même être utilisé si l'on connait son adresse (URL). Renvoie le département créé. - Exemple de résultat: departements-create.json
departement-edit
- Méthode: POST
- Permission:
ScoSuperAdmin
- Paramètres:
dept_acronym
- Data:
{ "visible":bool }
- Routes:
/departement/<string:dept_acronym>/edit
- Exemple d'utilisation:
/departement/edit
{ "visible": false }
- Résultat: Modifie un département. Seul le champs
visible
peut être modifié. L'acronyme ne peut pas être changé car il peut être mentionné dans de nombreux objets et documents, y compris à l'extérieur de ScoDoc. - Exemple de résultat: departements-edit.json
departement-delete
- Méthode: POST
- Permission:
ScoSuperAdmin
- Paramètres:
dept_acronym
- Routes:
/departement/<string:dept_acronym>/delete
- Exemple d'utilisation:
/departement/delete/EARTH
- Résultat: supprime définitivement un département. Toutes les données sont effacées (étudiants, formations, ...).
- Exemple de résultat: departements-delete.json
API Etudiant
Structure Etudiant
attribut | type | commentaire |
---|---|---|
id | int | id unique |
code_nip | string | non unique! |
code_ine | string | non unique! |
dept_id | ||
civilite | string | "M", "F" ou "X" |
nom | string | en majuscule |
nom_usuel | string | null si absent |
prenom | string | |
sort_key | [ string, string ] | nom-prenom pour trier |
Format long | ||
date_naissance | string | date ISO |
string | ||
emailperso | string | |
admission | admission | |
adresses | adresse* | |
boursier | ||
dept_acronym | string | |
dept_id | string | département du lieu de naissance |
lieu_naissance | string | lieu de naissance (ville) |
nationalite | string | |
photo_filename | string | |
scodoc7_id | string | de la forme 'EID9999' |
statut | string | 'I', 'D' ou 'X' |
etudiants
(supprimé)
- Méthode: GET
- Routes: `/etudiants
- Exemple d'utilisation:
/api/etudiants
- Résultat: Liste complète de tous les étudiants (passés ou présents) pour lequel l'utilisateur a la permission ScoView.
- Exemple de résultat: [etudiants.json] (samples/sample_etudiants.json.md)
etudiants-courants
- Méthode: GET
- Permission:
ScoView
- Routes:
/etudiants/courants
/etudiants/courants/long
- Exemple d'utilisation:
/api/etudiants/courants
- Résultat: Liste des étudiants inscrits dans un formsemestre
actuellement en cours. Avec
/long
, donne tous les attributs de l'étudiants (plus lent). - Exemple de résultat: etudiants-courants.json
etudiants-clef
- Méthode: GET
- Permission:
ScoView
- Paramètres:
etudid
,nip
,ine
- Routes:
/etudiants/etudid/<int:etudid>
ou/etudiants/nip/<string:nip>
ou/etudiants/ine/<string:ine>
- Exemple d'utilisation:
/api/etudiants/nip/1
- Résultat: Info sur le ou les étudiants correspondants.
Comme
/etudiant
mais renvoie toujours une liste. Si non trouvé, liste vide, pas d'erreur. Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a été inscrit dans plusieurs départements, on a plusieurs objets (1 par dept.). - Exemple de résultat: etudiants-clef.json
departement-etudiants
- Méthode: GET
- Permission:
ScoView
- Paramètres:
dept
,dept_id
- Routes:
/departement/id/<int:dept_id>/etudiants
/departement/<string:dept>/etudiants
- Exemple d'utilisation:
/api/departement/MMI/etudiants
- Résultat: liste tous les étudiants (passés ou présents) d'un département. On peut spécifier l'acronyme du département ("MMI") ou son id (un entier). Attention, la liste peut être longue: requête coûteuse à éviter.
- Exemple de résultat: departement-etudiants.json
formsemestre-etudiants[-long][-query]
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
- Query string:
etat
('I', 'D' ou 'DEF') - Routes:
/formsemestre/<int:formsemestre_id>/etudiants
/formsemestre/<int:formsemestre_id>/etudiants/query?etat=I,D,DEF
/formsemestre/<int:formsemestre_id>/etudiants/long
/formsemestre/<int:formsemestre_id>/etudiants/long/query?etat=I,D,DEF
- Exemple d'utilisation:
/api/formsemestre/1/etudiants/long
/api/formsemestre/1/etudiants/query?etat=D
- Résultat: Etudiants d'un formsemestre spécifié par son id.
Une clé (
sort_key
) reproduit [ nom, prenom ] sous forme ASCII, permettant le tri des étudiants. Avecquery
, La liste est restreinte aux étudiants inscrits (I
), démissionnaires (D
) ou défaillants (DEF
) si l'état est indiqué. Aveclong
, ajoute la date de naissance entre autre - Exemple de résultat:
group-etudiants[-query]
- Méthode: GET
- Permission:
ScoView
- Paramètres:
group_id
- Query string:
etat
('I', 'D' ou 'DEF') - Routes:
/group/<int:group_id>/etudiants
/group/<int:group_id>/etudiants/query
- Exemple d'utilisation:
/ScoDoc/api/group/1/etudiants
/ScoDoc/api/group/1/etudiants/query?etat=I
- Résultat: Etudiants d'un groupe spécifié par son id. Liste restreinte aux étudiants inscrits (I), démissionnaires (D) ou défaillants (DEF) si l'état est indiqué.
- Exemple de résultat:
etudiant
- Méthode: GET
- Permission:
ScoView
- Paramètres:
etudid
,nip
,ine
- Routes:
/etudiant/etudid/<int:etudid>
ou/etudiant/nip/<string:nip>
ou/etudiant/ine/<string:ine>
- Exemple d'utilisation:
/api/etudiant/nip/1
- Résultat: Retourne les informations sur l'étudiant correspondant à l'id passé en paramètres. Les codes INE et NIP sont uniques au sein d'un département. Si plusieurs objets étudiant ont le même code, on renvoie le plus récemment inscrit.
- Pour obtenir tous les étudiants répondant au critère, utiliser etudiant-clefs
- Exemple de résultat: etudiant.json
API Formation
Structure Formation
attribut | type | commentaire |
---|---|---|
dept_id | int | redondant avec departement.id ? |
acronyme | string | |
titre | string | URL encoded ? |
version | int | |
type_parcours | int | |
referentiel_competence_id | int | null si pas de référentiel associé |
id | int | id unique de formation |
titre_officiel | string | |
formation_code | string | défini la compatibilité avec d'autres formations |
code_specialité | string | |
departement | Département | pour /formations mais pas pour /formation ? |
formation_id | redondant avec id ? |
formations
- Méthode: GET
- Permission:
ScoView
- Routes:
/formations
- Exemple d'utilisation:
/ScoDoc/api/formations
- Résultat: Liste de toutes les formations (tous départements accessibles).
- Exemple de résultat: formations.json
formations_ids
- Méthode: GET
- Permission:
ScoView
- Routes:
/formations_ids
- Exemple d'utilisation:
/ScoDoc/api/formations_ids
- Résultat: Liste des ids de toutes les formations (tous départements accessibles).
- Exemple de résultat: formations_ids.json
formation
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formation_id
- Routes:
/formation/<int:formation_id>
- Exemple d'utilisation:
/ScoDoc/api/formation/1
- Résultat: Description de la formation.
- Exemple de résultat: formation.json
API Formsemestre
Les sessions de formation (qu'elles durent une année ou un mois) sont représentées par les formsemestre
.
Note sur les identifiants de formsemestre
Le session_id
peut être utilisé pour identifier de façon prévisible et
(presque) unique un formsemestre dans un établissement, ce qui est utile
notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion
d'emplois du temps ou de services d'enseignement). Cet identifiant est constitué
des informations suivantes:
- Département (RT, GEII, INFO...) (acronyme en majuscules)
- Nom parcours: BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
- Modalité: FI, FC, FA
- "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) dans la "formation" (le 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).
Structure Formsemestre
attribut | type | commentaire |
---|---|---|
id | int | id unique |
formsemestre_id | int | identification unique |
semestre_id | int | rang du semestre 1, ... |
elt_annee_apo | ??? | |
titre | string | |
titre_court | string | |
titre_num | string | |
session_id | string | cf. Note sur les identifiants de formsemestre |
block_moyennes | bool | inhibe le calcul des moyennes |
scodoc7_id | int | |
date_debut | date | |
date_fin | date | |
gestion_semestrielles | bool | |
gestion_compensation | bool | |
bul_bgcolor | string | Couleur (CSS) de fond du bulletin |
etat | bool | |
dept_id | int | |
modalite | string | "FI", "FA", ... |
bul_hide_xml | bool | |
resp_can_change_ens | bool | |
resp_can_edit | bool | |
ens_can_edit_eval | bool | |
elt_sem_apo | string | |
parcours | ???? | |
annee_scolaire | int | |
date_debut_iso | string | |
date_fin_iso | string | |
departement | Département | |
etape_apo | string | |
formation_id | int | |
formation | Formation | |
responsables | int* | liste des ids des enseignants responsables |
departement-formsemestres_ids
- Méthode: GET
- Permission:
ScoView
- Paramètres:
dept
- Routes:
/departement/id/<int:dept_id>/formsemestres_ids
/departement/<string:dept>/formsemestres_ids
- Exemple d'utilisation:
/api/departement/MMI/formsemestres_ids
- Résultat: Liste des id des formsemestres (passés ou présents) d'un département donné.
- Exemple de résultat: departement-formsemestres_ids.json
departement-formsemestres-courants
- Méthode: GET
- Permission:
ScoView
- Paramètres:
dept_id
- Routes:
/departement/id/<int:dept_id>/formsemestres_courants
/departement/<string:dept>/formsemestres_courants
- Exemple d'utilisation:
/api/departement/MMI/formsemestres_courants
- Résultat: Liste des formsemestres en cours d'un département donné.
- Exemple de résultat: departement-formsemestres-courants.json
formsemestres-query
- Méthode: GET
- Permission:
ScoView
- Paramètres: aucun
- Query string:
etape_apo
,annee_scolaire
,dept_acronym
,dept_id
- Route: `/formsemestres/query
- Exemple d'utilisation:
/api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021
- Résultat: Description d'un formsemestre. Si plusieurs paramètres sont donnés, c'est la conjonction (ET) des critères qui est recherchée. Si aucun formsemestre ne satisfait la requête, une liste vide est retournée.
- Exemple de résultat: formsemestres-query.json
etudiant-formsemestres
- Méthode: GET
- Permission:
ScoView
- Paramètres:
etudid
,nip
,ine
- Routes: :
/etudiant/etudid/<int:etudid>/formsemestres
ou/etudiant/nip/<string:nip>/formsemestres
ou/etudiant/ine/<string:ine>/formsemestres
- Exemple d'utilisation:
/etudiant/ine/1/formsemestres
- Résultat: Liste des semestres qu'un étudiant a suivi, triés par ordre chronologique.
- Exemple de résultat: etudiant-formsemestres.json
formsemestre
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
- Route:
/formsemestre/<int:formsemestre_id>
- Exemple d'utilisation:
/api/formsemestre/1
- Résultat: Description du formsemestre.
- Exemple de résultat: formsemestre.json
API Groupe
partition-group-create
- Méthode: POST
- Permission:
ScoEtudChangeGroups
- Paramètres:
partition_id
- Data:
{ group_name : <string> }
- Routes:
/partition/<int:partition_id>/create
- Exemple d'utilisation:
/ScoDoc/api/partition/1962/create
{ "group_name" : "A" }
- Résultat: Crée un groupe dans une partition.
- Exemple de résultat: partition-create.json
group-edit
- Méthode: POST
- Permission:
ScoEtudChangeGroups
- Paramètres:
group_id
- Data:
{ group_name : <string> }
- Routes:
/group/<int:group_id>/edit
- Exemple d'utilisation:
/ScoDoc/api/group/4581/edit
{ "group_name" : "nouveau" }
- Résultat: Renomme un groupe.
- Exemple de résultat: group-edit.json
partition-groups-order
- Méthode: POST
- Permission:
ScoEtudChangeGroups
- Paramètres:
partition_id
- Data:
[ <int:group_id1>, <int:group_id2>, ... ]
- Routes:
/partition/<int:partition_id>/groups/order
- Exemple d'utilisation:
/ScoDoc/api/partition/1962/groups/order
[ 4383, 4379, 4380, 4381, 4382, 4384 ]
- Résultat: Spécifie l'ordre des groupes d'une partition.
- Exemple de résultat: partition-groups-order.json
group-delete
- Méthode: POST
- Permission:
ScoEtudChangeGroups
- Paramètres:
group_id
- Routes:
/group/<int:group_id>/delete
- Exemple d'utilisation:
/ScoDoc/api/group/4581/delete
- Résultat: Supprime un groupe.
- Exemple de résultat: group-delete.json
etudiant-formsemestre-groups
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
,etudid
,nip
,ine
- Routes:
/etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups
ou/etudiant/nip/<string:nip>/semestre/<int:formsemestre_id>/groups
ou/etudiant/ine/<string: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: etudiant-formsemestres-groups.json
group-set_etudiant
- Méthode: POST
- Permission:
ScoEtudChangeGroups
- Paramètres:
group_id
,etudid
- Routes:
/group/<int:group_id>/set_etudiant/<int:etudid>
- Exemple d'utilisation:
/ScoDoc/api/group/4085/set_etudiant/12108
- Résultat: Affecte un étudiant dans un groupe.
- Exemple de résultat: groupes-set_etudiant.json
group-remove_etudiant
- Méthode: POST
- Permission:
ScoEtudChangeGroups
- Paramètres:
group_id
,etudid
- Routes:
/group/<int:group_id>/remove_etudiant/<int:etudid>
- Exemple d'utilisation:
/ScoDoc/api/group/4085/remove_etudiant/12108
- Résultat: Retire un étudiant d'un groupe.
- Exemple de résultat: groupes-remove_etudiant.json
API Jury
formsemestre-decisions_jury
- Permission:
ScoView
- Méthode: GET
- Paramètres:
formsemestre_id
- Routes:
/formsemestre/<int:formsemestre_id>/decisions_jury
- Exemple d'utilisation:
/ScoDoc/api/formsemestre/1/jury
- Résultat: Retourne le récapitulatif des décisions jury
- Exemple de résultat: formsemestre-decisions_jury.json `
API Moduleimpl
Structure ModuleImpl
Le moduleimpl est la mise en place d'un module dans un formsemestre (avec son responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut être obtenu par l'entrée formsemestre-programme
attribut | type | commentaire |
---|---|---|
id | int | identifiant unique |
responsable_id | int | id du responsable de module |
computation_expr | string | unused |
module_id | int | id du module |
formsemestre_id | int | id du formsemestre |
moduleimpl_id | int | **redondance id? |
ens | User# | liste des ids des enseignants du moduleimpl |
module | Module |
moduleimpl
- Méthode: GET
- Permission:
ScoView
- Paramètres:
moduleimpl_id
- Routes:
/moduleimpl/<int:moduleimpl_id>
- Exemple d'utilisation:
/ScoDoc/api/moduleimpl/1
- Résultat: Description du moduleimpl.
- Exemple de résultat: moduleimpl.json
API Partition
Structure Partition
L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieurs partitions (types de groupes). Chaque partition est constituée d'un nombre quelconque de groupes d'étudiants.
attribut | type | commentaire |
---|---|---|
id | int | identifiant unique |
partition_name | string | nom de la partition |
numero | int | |
bul_show_rank | affichage sur bulletin | |
groups_editable | bool | verrou (liste des groupes) |
formsemestre_id | int | formsemestre hôte |
show_in_lists | bool | |
groups | Group* | liste des groupes de la partition |
formsemestre-partitions
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
- Routes:
/formsemestre/<int:formsemestre_id>/partitions
- Exemple d'utilisation:
/ScoDoc/api/formsemestre/911/partitions
- Résultat: Liste de toutes les partitions d'un formsemestre.
- Exemple de résultat: formsemestre-partitions.json
partition
- Méthode: GET
- Permission:
ScoView
- Paramètres:
partition_id
- Routes:
/partition/<int:partition_id>
- Exemple d'utilisation:
/ScoDoc/api/partition/1963
- Résultat: Description d'une partition (y compris la liste de ses groupes).
- Exemple de résultat: partition.json
formsemestre-partition-create
- Méthode: POST
- Permission:
ScoEtudsChangeGroups
- Paramètres:
formsemestre_id
- Data:
{ "partition_name" : <string> }
- Routes:
/formsemestre/<int:formsemestre_id>/partition/create
{ "partition_name" : "PART" }
- Exemple d'utilisation:
/ScoDoc/api/formsemestre/944/partition/create
- Résultat: Crée une nouvelle partition dans un formsemestre.
- Exemple de résultat: formsemestre-partition-create.json
partition-edit
- Méthode: POST
- Permission:
ScoEtudsChangeGroups
- Paramètres:
partition_id
- Data:
{ partition_name : <string> }
- Routes:
/partition/<int:partition_id>/edit
- Exemple d'utilisation:
/ScoDoc/api/partition/2047/edit
{ "partition_name" : "PART4" }
- Résultat: Renomme une partition
- Exemple de résultat: partition-edit.json
formsemestre-partitions-order
- Méthode: POST
- Permission:
ScoEtudsChangeGroups
- Paramètres:
formsemestre_id
- Data:
[ <int:partition_id1>, <int:partition_id2>, ... ]
- Routes:
/formsemestre/<int:formsemestre_id>/partitions/order
- Exemple d'utilisation:
/ScoDoc/api/formsemestre/944/partitions/order
[ 2048, 2054 ]
- Résultat: Spécifie l'ordre des partitions d'un formsemestre.
- Exemple de résultat: formsemestre-partitions-order.json
partition-delete
- Méthode: POST
- Permission:
ScoEtudsChangeGroups
- Paramètres:
partition_id
- Routes:
/partition/<int:partition_id>/delete
- Exemple d'utilisation:
/ScoDoc/api/partition/2047/delete
- Résultat: Supprime une partition.
- Exemple de résultat: partition-delete.json
partition-remove_etudiant
- Méthode: POST
- Permission:
ScoEtudsChangeGroups
- Permission:
ScoEtudChangeGroups
- Paramètres:
partition_id
- Routes:
/partition/<int:partition_id>/remove_etudiant/<int:etudid>
- Exemple d'utilisation:
/ScoDoc/api/partition/1962/remove_etudiant/12107
- Résultat: Retire un étudiant des groupes de la partition.
- Exemple de résultat: partition-remove_etudiant.json
API Role
Les rôles ont un nom et sont associés à un ensemble de permissions. Un utilisateur pourra être associé à un ou plusieurs rôles dans chaque département (ainsi, il ou elle peut enseigner dans un département et être administrateur d'un autre).
roles
- Méthode: GET
- Permission:
ScoUsersView
- Routes:
/roles
- Exemple d'utilisation:
/roles
- Résultat: Liste de tous les rôles.
- Exemple de résultat: roles.json
role
- Méthode: GET
- Permission:
ScoUsersView
- Routes:
/role/<str:role_name>
- Exemple d'utilisation:
/role/Ens
- Résultat: Liste le rôle indiqué. 404 si inexistant.
- Exemple de résultat: role.json
role-add_permission
- Méthode: POST
- Permission:
ScoSuperAdmin
- Routes:
/role/<str:role_name>/add_permission/<str:perm_name>
- Exemple d'utilisation:
/role/Ens/add_permission/ScoView
- Résultat: Ajoute la permission au rôle. 404 si l'un des deux n'existe pas. Note: la liste des permissions est donnée sur ConfigPermissions.
- Exemple de résultat: role-add_permission.json
role-remove_permission
- Méthode: POST
- Permission:
ScoSuperAdmin
- Routes:
/role/<str:role_name>/remove_permission/<str:perm_name>
- Exemple d'utilisation:
/role/Ens/remove_permission/ScoView
- Résultat: Retire la permission au rôle. 404 si l'un des deux n'existe pas. Si le rôle n'a pas la permission, ne fait rien.
- Exemple de résultat: role-remove_permission.json
role-create
- Méthode: POST
- Permission:
ScoSuperAdmin
- Data:
{ "permissions" : [ permission, ... ] }
- Routes:
/role/create/<str:role_name>
- Exemple d'utilisation:
/role/create/LaveurDecarreaux
{ "permissions" : [ 'ScoView', 'ScoUsersView' ] }
- Résultat: Crée un nouveau rôle, avec les permissions indiquées.
- Exemple de résultat: role-create.json
role-delete
- Méthode: POST
- Permission:
ScoSuperAdmin
- Routes:
/role/<str:role_name>/delete
- Exemple d'utilisation:
/role/LaveurDeCarreaux/delete
- Résultat: Supprime ce rôle.
- Exemple de résultat: role-delete.json
role-edit
- Méthode: POST
- Permission:
ScoSuperAdmin
- Data:
{ "permissions" : [ permission, ... ] }
- Routes:
/role/edit/<str:role_name>
- Exemple d'utilisation:
/role/create/LaveurDecarreaux
{ "name" : "LaveurDeVitres", "permissions" : [ 'ScoView' ] }
- Résultat: Modifie le rôle: son nom et/ou ses permissions.
- Exemple de résultat: role-edit.json
API User, Permissions
user
- Méthode: GET
- Permission:
ScoUsersView
- Paramètres:
user_id
- Route:
/user/<int:user_id>
- Exemple d'utilisation:
/api/user/1
- Résultat: Retourne la description d'un utilisateur.
- Exemple de résultat: user.json
user-create
- Méthode: POST
- Permission:
ScoUsersAdmin
- Data:
{
"user_name": str,
"dept": str or null,
"nom": str,
"prenom": str,
"active":bool (default True)
}
- Routes:
/user/create
- Résultat: Crée un nouvel utilisateur.
user_name
est le login, unique et non modifiable. L'utilisateur est normalement rattaché à un département, sauf si est "super-administrateur". - Exemple de résultat: user-create.json
users-query
- Méthode: GET
- Permission:
ScoUsersView
- Routes:
/users/query?departement=dept_acronym&active=1&starts_with=<str:nom>
- Résultat: Liste d'utilisateurs, filtrés par département, statut, début de nom (paramètres tous optionnels). Seuls les utilisateurs que l'on a la permission de voir sont listés.
- Exemple de résultat: users-query.json
user-edit
- Méthode: POST
- Permission:
ScoUsersAdmin
- Data:
{
"dept": str or null,
"nom": str,
"prenom": str,
"active":bool (default True)
}
- Routes:
/user/<int:uid>/edit
- Résultat: Modifie l'utilisateur d'UID indiqué.
- Exemple de résultat: user-edit.json
user-password
- Méthode: POST
- Permission:
ScoUsersAdmin
- Data:
{ "password": str }
- Routes:
/user/<int:uid>/password
- Exemple d'utilisation:
/user/3/password
`{ "password": "averycomplicatedpassaword" }
- Résultat: Modifie le mot de passe de l'utilisateur désigné par son UID. L'opération peut être rejetée si le mot de passe ne satisfait pas les conditions requises (trop simple par exemple), avec le retour suivant:
{
"error": "Bad Request",
"status": 400,
"message": "user_password: invalid password"
}
```
- Exemple de résultat: user-password.json
user-role-add
- Méthode: POST
- Permission:
ScoSuperAdmin
- Routes:
/user/<int:uid>/role/<str:role_name>/add[/departement/<string:dept_acronym>]
- Résultat: Attribue le rôle à l'utilisateur, dans le département indiqué (ou tous si le département n'est pas spécifié).)
- Exemple de résultat: user-role-add.json
user-role-remove
- Méthode: POST
- Permission:
ScoUsersAdmin
- Routes:
/user/<int:uid>/role/<str:role_name>/remove[/departement/<string:dept_acronym>]
- Résultat: Retire le rôle à l'utilisateur.
- Exemple de résultat: user-role-remove.json
permissions
- Méthode: GET
- Permission:
ScoUsersView
- Routes:
/permissions
- Résultat: Liste des noms des permissions. Ces permissions ne sont pas modifiables, mais de nouvelles peuvent apparaitre lors des mises à jour du logiciel. Voir ConfigPermissions.
- Exemple de résultat: permissions.json
** API Bulletin, Evaluations, Notes**
formsemestre-bulletins
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
- Route: `/formsemestre/int:formsemestre_id/bulletins
- Exemple d'utilisation:
/api/formsemestre/1/bulletins
- Résultat: Bulletins d'un formsemestre spécifié par son id.
- Exemple de résultat: formsemestre-bulletins.json
etudiant-formsemestre-bulletin
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules pour un formsemestre spécifié par son id. Par défaut les valeurs numériques sont formattées en chaînes. Si format=raw, valeurs numériques mais pas JSON compliant à cause des NaN.
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
,etudid
,nip
,ine
- Query string:
format
- Routes:
/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]
ou/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]
ou/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]
- Exemple d'utilisation:
/etudiant/nip/1/formsemestre/1/bulletin
- Résultat: Bulletin de l'étudiant dans le formsemestre.
Deux types de variantes possibles:
- versions
long
etshort
(long
par défaut, ajoutez/short
pour la version plus courte). - version
json
etpdf
(json
par défaut, ajoutez/pdf
pour la version pdf)
- versions
- Exemple de résultat: etudiant-formsemestre-bulletin.json
formsemestre-programme
- Méthode: GET
- Permission:
ScoView
- Paramètres:
dept
,formsemestre_id
- Routes:
/formsemestre/<int:formsemestre_id>/programme
- Exemple d'utilisation:
/ScoDoc/api/formsemestre/1/programme
- Résultat: Retourne la struture d'un formsemestre sous 5 entrées d'un dictionnaire:
ues
: liste des UEs,ressources
: liste des ressources (BUT),saes
: liste des saes (BUT),modules
: liste des modules classiques (DUT ou sport/culture)malus
: listes des modules de type bonus/malus.
- Exemple de résultat: formsemestre-programme.json
formsemestre-resultats
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
- Query string:
format
- Route:
/formsemestres/resultats
- Exemple d'utilisation:
/api/formsemestre/1/resultats
- Résultat: formsemestre-resultats.json
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules pour un formsemestre spécifié par son id. Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw, valeurs numériques mais pas JSON compliant à cause des NaN.
- Exemple de résultat:
moduleimpl-evaluations
- Méthode: GET
- Permission:
ScoView
- Paramètres:
moduleimpl_id
- Routes:
/moduleimpl/<int:moduleimpl_id>/evaluations
- Exemple d'utilisation:
/ScoDoc/api/moduleimpl/1/evaluations
- Résultat: Retourne la liste des évaluations à partir de l'id d'un moduleimpl (quel que soit leur statut).
- Exemple de résultat: moduleimpl-evaluations.json
evaluations-notes
- Méthode: GET
- Permission:
ScoView
- Paramètres:
evaluation_id
- Routes:
/evaluation/<int:evaluation_id>/notes
- Exemple d'utilisation:
/evaluation/1491/notes
- Résultat: Retourne la liste des notes d'une évaluation. Les valeurs sont
non normalisées (le champ
note_max
indique le barème), et peuvent contenir des chaînes de caractères: ABS, EXC, DEM, ... - Exemple de résultat: evaluation-notes.json
formsemestre-etat_evals
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formsemestre_id
- Routes:
/formsemestre/<int:formsemestre_id>/etat_evals
- Exemple d'utilisation:
/ScoDoc/api/formsemestre/1/etat_evals
- Résultat: Retourne les informations sur l'état des évaluations d'un semestre donné
- Exemple de résultat: formsemestre-etat_evals.json
API Export, Référentiel
formation-export
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formation_id
,export_ids
(False par défaut. Ajouter/with_ids
pour le passer à True) - Routes:
/formation/<int:formation_id>/export
/formation/<int:formation_id>/export_with_ids
- Exemple d'utilisation:
/ScoDoc/api/formation/formation_export/1
- Résultat: Retourne la formation, avec UE, matières, modules
- Exemple de résultat: formation-export.json
formation-referentiel_competences
- Méthode: GET
- Permission:
ScoView
- Paramètres:
formation_id
- Routes:
/formation/<int:formation_id>/referentiel_competences
- Exemple d'utilisation:
api/formation/1/referentiel_competences
- Résultat: Le référentiel de compétences d'une formation donnée (json). (pas toujours présent)
- Exemple de résultat: formation-referentiel_competences.json
API Logos
logos
- Méthode: GET
- Permission:
ScoSuperAdmin
- Paramètres : Aucun
- Route :
/logos
- Exemple d'utilisation :
/ScoDoc/api/logos
- Résultat : Liste des noms des logos définis pour le site scodoc.
- Exemple de résultat: logos.json
logo
- Méthode: GET
- Permission:
ScoSuperAdmin
- Paramètres : Aucun
- Route:
/logo/<string:nom>
- Exemple d'utilisation :
/ScoDoc/api/logo/header
- Résultat : l'image (format png ou jpg. le format retourné dépend du format sous lequel l'image a été initialement enregistrée)
- Exemple de résultat: logo.json
departement-logos
- Méthode: GET
- Permission:
ScoSuperAdmin
- Paramètres: Aucun
- Route :
/departement/<string:dept>/logos
/departement/id/<int:departement_id>/logos
- Exemple d'utilisation :
/departement/<string:dept>/logos
/departement/id/<int:departement_id>/logos
- Résultat : Liste des noms des logos définis pour le département visé qui peut être désigné par son id ou par son acronyme (selon la forme de la route).
- Exemple de résultat: departement-logos.json
departement-logo
- Méthode: GET
- Permission:
ScoSuperAdmin
- Paramètres : Aucun
- Route :
/departement/<string:dept>/logo/<string:nom>
/departement/id/<int:departement_id>/logo/<string:nom>
- Exemple d'utilisation:
/ScoDoc/api/departement/MMI/logo/header
/ScoDoc/api/departement/id/3/logo/header
- Résultat : l'image (format png ou jpg)
- Exemple de résultat: departement-logo.json
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
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
(deviendraapi/absences/billets/etud/ etudid>
)Absences/AddBilletAbsence
(deviendraapi/absences/billet/add
)Absences/XMLgetAbsEtud
(deviendraapi/absences/ etudid>
, en json)Notes/evaluation_listenotes
(non existante en ScoDoc9, trop complexe)Notes/formsemestre_id
(deviendraapi/formsemestre
)Notes/formsemestre_bulletinetud
(deviendraapi/etud/<etudid>/bul/<formsemestre_id>
)Notes/XMLgetFormsemestres
(non existante en ScoDoc9, redondant avecapi/formsemestre
?)etud_info
ouXMLgetEtudInfos
ouAbsences/XMLgetEtudInfos
ouNotes/XMLgetEtudInfos
(deviendra/api/etud/<etudid>
)groups_view
(deviendragroups
)
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.