DocScoDocPE/docs/ScoDoc9API.md

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)

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).

# 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).

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_nameet 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 ê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 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, courant, long, ...) sont des options Les autre 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)

Référence

Carte syntaxique

Tableau récapitulatif des point de l'API

Ce tableau est trié selon le type des informations retourné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
departement*****	tous les depts	GET	departements
departement**#**	tous les ids des depts	GET	departements-ids
departement	recherche par id	GET	departement
departement	recherche par acronyme	GET	departement
formation*****	toutes les formations accessibles	GET	formations
formation**#**	ids des formations accessibles	GET	formations-ids
formation	une formation	GET	formation
export		GET	formation-export
export**+**		GET	formation-export_with_ids
referentiel_competences		GET	formation-referenciel_competences
formsemestre**#**		GET	departement-formsemestres_ids
formsemestre*****		GET	departement-formsemestres_courants
formsemestre*****		GET	formsemestre-query
formsemestre*****		GET	etudiant-formsemestres
formsemestre		GET	formsemestre
moduleimpl		GET	moduleimpl
partition*****		GET	formsemestre-partitions
partition		GET	partition
partition:CREATE		POST	formsemestre-partition-create
partition:EDIT		POST	partition-edit
partition:ACTION		POST	formsemestre-partitions-order
partition:DELETE		POST	partition-delete
partition:ACTION		POST	partition-remove_etudiant
group:CREATE		POST	partition-group-create
group:EDIT		POST	group-edit
group:ACTION		POST	partition-groups-order
group:DELETE		POST	group-delete
group*		POST	etudiant-formsemestre-groups
group:ACTION		GET	group-set_etudiant
group:ACTION		POST	group-remove_etudiant
etudiant*****	tous les étudiants	GET	etudiants
etudiant*****	recherche par etudid, nip ou i	GET	etudiants-clé
etudiant*****	les étudiants actuels	GET	etudiants-courant
etudiant*****		GET	departement-etudiants
etudiant*****		GET	formsemestre-etudiants
etudiant*****		GET	formsemestre-etudiants-defaillants
etudiant*****		GET	formsemestre-etudiants-demissionnaires
etudiant*****		GET	group-etudiants
etudiant*****		GET	group-etudiants-query
etudiant		GET	etudiant
		GET	jury-formsemestre-decisions_jury
bulletin*****		GET	formsemestre-bulletin
bulletin		GET	etudiant-formsemestre-bulletin
programme		GET	formsemestre-programme
		GET	formsemestre-etat_evals
		GET	formsemestre-resultats
evaluation*		GET	evaluations
note*		GET	evaluation-notes
user		GET	user

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
• Routes: /departements_ids
• Résultat: Liste des id départements (visibles ou non).
• Exemple de résultat:

  [ 1888, 999, 165 ]
  

departement

• Méthode: GET
• Routes:
  • /departement/id/<int:dept_id>
  • /departement/<string:dept>
• Résultat: Un département
• Exemple de résultat: departement.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
• 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
• 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:

[17, 99, 32]

formation

• Méthode: GET
• 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 mmoyennes
scodoc7_id	int
date_debut	date
date_fin	date
gestion_semestrielles	bool
gestion_compensation	bool
bul_bgcolor	string	Couleur (CSS) de fond du bulletin
etat	bool
dept_id	int
modalite	string	"FI", "FA", ...
bul_hide_xml	bool
resp_can_change_ens	bool
resp_can_edit	bool
ens_can_edit_eval	bool
elt_sem_apo	string
parcours	????
annee_scolaire	int
date_debut_iso	string
date_fin_iso	string
departement	Département
etape_apo	string
formation_id	int
formation	Formation
responsables	int*	liste des ids des enseignants responsables

departement-formsemestres_ids

• Méthode: GET
• Paramètres: dept
• 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: [ 28, 99, 3 ]

departement-formsemestres-courants

• Méthode: GET
• 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
• 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.json

etudiant_formsemestres

• Méthode: GET
• 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
• Paramètres: formsemestre_id
• Route: /formsemestre/<int:formsemestre_id>
• Exemple d'utilisation: /api/formsemestre/1
• Résultat: Description du formsemestre.
• Exemple de résultat:

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
• Paramètres: moduleimpl_id
• Routes: /moduleimpl/<int:moduleimpl_id>
• Exemple d'utilisation: /ScoDoc/api/formation/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
• 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
• 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
• 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:

partition-edit

• Méthode: POST
• 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

formsemestre-partition-order

• Méthode: POST
• Paramètres: formsemestre_id
• Data: [ <int:partition_id1>, <int:partition_id2>, ... ]
• Routes: /formsemestre/<int:formsemestre_id>/partition/order
• Exemple d'utilisation: /ScoDoc/api/formsemestre/944/partition/order

[ 2048, 2054 ]

• Résultat: Spécifie l'ordre des partitions d'un formsemestre.
• Exemple de résultat:

partition-delete

• Méthode: POST
• 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-remove_etudiant

• Méthode: POST
• 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

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

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

partition-groups-order

• Méthode: POST
• 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:

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

etudiant-formsemestre-groupes

• Méthode: GET
• 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: groupes-formsemestre-etudiant.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

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

API Etudiant

Structure Etudiant

attribut	type	commentaire
id	int	id unique
code_nip	string	non unique!
code_ine	string	non unique!
dept_id
civilite	string	"M", "F" ou "X"
nom	string	en majuscule
nom_usuel	string	null si absent
prenom	string
		Format long
date_naissance	string	date ISO
email	string
emailperso	string
admission	admission
adresses	adresse*
boursier
dept_acronym	string
dept_id	string	département du lieu de naissance
lieu_naissance	string	lieu de naissance (ville)
nationalite	string
photo_filename	string
scodoc7_id	string	de la forme 'EID9999'
statut	string	'I', 'D' ou 'X'

etudiants

• Méthode: GET
• Routes: `/etudiants
• 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: tous-les-etudiant.json

etudiants-clef

• Méthode: GET
• 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.json

etudiants-courants

• Méthode: GET
• 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

departement-etudiants

• Méthode: GET
• 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:

  [
    {
          "civilite": "M", // M, F ou X
          "ine": "7899X61616",
          "code_nip": "F6777H88",
          "date_naissance": null,
          "email": "toto@toto.fr",
          "emailperso": null,
          "etudid": 18,
          "nom": "MOREL", // en majuscules
          "prenom": "JACQUES"
    },
    ...
  ]
  

formsemestre-etudiants

• Méthode: GET
• Paramètres: formsemestre_id
• Routes: /formsemestre/<int:formsemestre_id>/etudiants XXX voir si filtrage par état (dem, def, ...)
• Route:
  • /formsemestres/etudiants
  • /formsemestres/etudiants/demissionnaires
  • /formsemestres/etudiants/defaillants
• Exemple d'utilisation: /api/formsemestre/1/etudiants
• Résultat: Etudiants d'un formsemestre spécifié par son id. Liste est restreinte aux étudiants démissionnaires/défaillants si l'option correspondante est ajoutée au chemin
• Exemple de résultat: formsemestre-etudiants.json

formsemestre-etudiants-etat

• Méthode: GET
• Paramètres: formsemestre_id, etat (par défaut égal à "I" pour les étudiants inscrits)
• Résultat: les étudiants inscrits à ce semestres XXX préciser état (DEM, DEF))

group-etudiants

• Méthode: GET
• Paramètres: group_id
• Routes: /group/<int:group_id>/etudiants
• Exemple d'utilisation: /ScoDoc/api/group/1/etudiants
• Résultat: Retourne la liste des étudiants dans un groupe.
• Exemple de résultat: group-etudiants.json

groups-etudiants-query

• Méthode: GET
• Paramètres: group_id
• Query string: etat ('I', 'D' ou 'DEF')
• Routes: /group/<int:group_id>/etudiants/query
• Exemple d'utilisation: /ScoDoc/api/group/1/etudiants/query?etat=I
• Résultat: Retourne la liste des étudiants dans un groupe.
• Exemple de résultat: group-etudiants-query.json

etudiant

• Méthode: GET
• 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 ramène le plus récemment inscrit.
• Exemple de résultat: etudiant.json

API Programme, Référentiel

formation-export

• Méthode: GET
• 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
• 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 Bulletin, Evaluations, Notes**

formsemestre-bulletins

• Méthode: GET
• 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.

• Exemple de résultat:

• Méthode: GET

• Paramètres: formsemestre_id, etudid, nip, ine

• Routes: /etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf] ou /etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf] ou /etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf]

On peut spécifier le format: longou short, et indiquer si l'on veut le bulletin PDF.

• Exemple d'utilisation: /etudiant/nip/1/formsemestre/1/bulletin
• Résultat: Bulletin de l'étudiant dans le formsemestre. Deux versions disponibles long et short (par défaut long ajoutez /short pour la version plus courte).
• Exemple de résultat: bulletin-formsemestre-etudiant.json

formsemestre-programme

• Méthode: GET
• Paramètres: dept, formsemestre_id
• Routes: /formsemestre/<int:formsemestre_id>/programme
• Exemple d'utilisation: /ScoDoc/api/formsemestre/1/programme
• Résultat: Retourne la liste des UEs, modules, ressources et SAE d'un semestre.
• Exemple de résultat: formsemestre-programme.json

formsemestre-etat_evals

• Méthode: GET
• Paramètres: formsemestre_id
• Route: /formsemestre/<int:formseemestre_id>/etat_evals
• Exemple d'utilisation: /api/formsemestre/1/etat_evals
• Résultat: informations sur les évaluations d'un formsemestre spécifié par son id.
• Exemple de résultat: formsemestre-etat-eval.json

formsemestre-resultats

• Méthode: GET
• 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:

evaluations

• Méthode: GET
• 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

evaluations/notes

• Méthode: GET
• Paramètres: evaluation_id
• Routes: /evaluations/eval_notes/<int:evaluation_id>
• Exemple d'utilisation: /ScoDoc/api/evaluations/notes/1
• Résultat: Retourne la liste des notes d'une évaluation
• Exemple de résultat: TODO XXX

formsemestre-etat_evals

• Méthode: GET
• 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

formsemestre-programme

• Méthode: GET
• Paramètres: dept, formsemestre_id
• Routes: /formsemestre/<int:formsemestre_id>/programme
• Exemple d'utilisation: /ScoDoc/api/formsemestre/1/programme
• Résultat: Retourne la liste des UEs, modules, ressources et SAE d'un semestre.
• Exemple de résultat: formsemestre-programme.json

formsemestre-resultats

• Méthode: GET
• Paramètres: formsemestre_id
• **Query string: format
• Route: /formsemestres/resultats
• Exemple d'utilisation: /api/formsemestre/1/resultats
• Résultat: Retourne les résultats pour un formsemestre
• Exemple de résultat: formsemestre-resultats.json

API User

user

• Méthode: GET
• 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

API Jury

formsemestre-decision_jury

• Méthode: GET
• Paramètres: formsemestre_id
• Routes: /formsemestre/<int:formsemestre_id>/decision_jury
• Exemple d'utilisation: /ScoDoc/api/formsemestre/1/jury
• Résultat: Retourne le récapitulatif des décisions jury
• Exemple de résultat:

  XXX A COMPLETER
  

API Logos

logos

• Méthode: GET
• Paramètres: format (json, xml), json par défaut
• Route : /ScoDoc/api/logos
• Exemple d'utilisation : /ScoDoc/api/logos?format=xml
• Résultat : Liste des noms des logos définis pour le site scodoc.
• Exemple de résultat: ['header', 'footer', 'custom']

XXX vérifier si on supporte XML et pour qui ?

logo

• Méthode: GET
• Paramètres : Aucun
• Route: /logos/<string:nom>
• Exemple d'utilisation : /ScoDoc/api/logo/header
• Résultat : l'image (format png ou jpg)

departement-logos

• Méthode: GET
• Paramètres: format (json, xml)
• Route : /departements/<string:dept>/logos
• Exemple d'utilisation : /ScoDoc/api/departements/MMI/logos
• Résultat : Liste des noms des logos définis pour le département visé.
• Exemple de résultat: ['footer', 'signature', 'universite']

departement-logo

• Méthode: GET
• Paramètres : Aucun
• Route: /departements/<string:dept>/logo/<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

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.