viennet 8528217d5f Documentation API et nouveaux samples

2024-07-27 14:34:32 +03:00

73 KiB

Raw Blame History

API pour ScoDoc 9

!!! warning "Attention" Page générée par la commande flask gen-api-doc. Ne pas modifier manuellement.

L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux objets de l'application via une API REST.

Les composants internes de ScoDoc, et notamment le schéma de la base de données, sont susceptibles d'évoluer à tout moment sans préavis: il est vivement déconseillé d'écrire une extension ne passant pas par l'API. Vous ne devez même pas supposer qu'il existe une base de données SQL.

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 (contacts) (et canal #API du Discord développeurs si vous y avez accès).

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 le guide développeurs)

L'URL complète est de la forme: https://scodoc.example.com/ScoDoc/api/<fonction>. ( à choisir dans Référence)

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, UsersView, ScoSuperAdmin, ...) peuvent être requis. La consultation du tableau récapitulatif ou la ligne permissionde 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;
la documentation développeurs et sur les vues de l'API.

!!! note

* Si vous utilisez le CAS, pensez à laisser les comptes utilisateurs API se
connecter via ScoDoc sans CAS. Pour cela, cocher l'option
*Autorise connexion via CAS si CAS est activé*
dans leur formulaire de configuration.

* Si l'utilisateur est associé à un département (cas des comptes créés via l'interface Web),
il ne pourra accéder à l'API que via une *route départementale*, c'est à dire une route comprenant
l'acronyme de son département, de la forme `https://...//ScoDoc/DEPARTEMENT/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 via les routes départementales de la forme https://scodoc.monsite.tld/ScoDoc/<dept_acronyme>/api/<fonction> pour un accès avec des droits restreints au département indiqué. La liste des <fonctions> est donnée ci-dessous dans Référence.

Authentification

Lors de votre authentification (connexion avec login et mot de passe) à 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 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, département, formation, formsemestre, groupe, etudiant, bulletin, absence, logo, programme, évaluation, résultat, décision 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

![carte_syntaxique](img/API_Chart.svg)

(carte générée avec flask gen-api-doc)

Tableau récapitulatif des entrées de l'API

Route	Méthode	Permission
assiduite	GET	ScoView
assiduite_create	POST	AbsChange
assiduite_delete	POST	AbsChange
assiduite_edit	POST	AbsChange
assiduite_justificatifs	GET	ScoView
assiduites	GET	ScoView
assiduites_count	GET	ScoView
assiduites_create	POST	AbsChange
assiduites_edit	POST	AbsChange
assiduites_evaluations	GET	ScoView
assiduites_formsemestre	GET	ScoView
assiduites_formsemestre_count	GET	ScoView
assiduites_group	GET	ScoView
autorisation_inscription_delete	POST	EtudInscrit
billets_absence_create	POST	Aucune permission requise
billets_absence_delete	POST	Aucune permission requise
billets_absence_etudiant	GET	Aucune permission requise
bulletin	GET	ScoView
bulletins	GET	ScoView
decisions_jury	GET	ScoView
departement_by_acronym	GET	ScoView
departement_create	POST	ScoSuperAdmin
departement_delete	POST	ScoSuperAdmin
departement_edit	POST	ScoSuperAdmin
departement_etudiants	GET	ScoView
departement_etudiants_by_id	GET	ScoView
departement_formsemestres_courants	GET	ScoView
departement_formsemestres_ids	GET	ScoView
departement_formsemestres_ids_by_id	GET	ScoView
departement_get	GET	ScoView
departement_logos	GET	ScoSuperAdmin
departement_logos_by_id	GET	ScoSuperAdmin
departements_ids	GET	ScoView
departements_list	GET	ScoView
etudiant	GET	ScoView
etudiant_annotation	POST	EtudInscrit
etudiant_annotation_delete	POST	EtudInscrit
etudiant_create	POST	EtudInscrit
etudiant_edit	POST	EtudInscrit
etudiant_formsemestres	GET	ScoView
etudiant_get_photo_image	GET	ScoView
etudiant_groups	GET	ScoView
etudiants	GET	ScoView
etudiants_by_name	GET	ScoView
etudiants_courants	GET	ScoView
evaluation_assiduites	GET	ScoView
evaluation_create	POST	EnsView
evaluation_delete	POST	EnsView
evaluation_notes	GET	ScoView
evaluation_set_notes	POST	EnsView
formation_export_by_formation_id	GET	ScoView
formation_get	GET	ScoView
formation_module_edit	POST	EditFormation
formation_module_get	GET	ScoView
formation_module_set_code_apogee	POST	EditFormation
formations	GET	ScoView
formations_ids	GET	ScoView
formsemestre_edit	POST	EditFormSemestre
formsemestre_edt	GET	ScoView
formsemestre_etat_evaluations	GET	ScoView
formsemestre_etudiants	GET	ScoView
formsemestre_get	GET	ScoView
formsemestre_partitions	GET	ScoView
formsemestre_programme	GET	ScoView
formsemestre_resultat	GET	ScoView
formsemestre_set_apo_etapes	POST	EditApogee
formsemestre_set_elt_annee_apo	POST	EditApogee
formsemestre_set_elt_passage_apo	POST	EditApogee
formsemestre_set_elt_sem_apo	POST	EditApogee
formsemestre_set_partitions_order	POST	ScoView
formsemestres_query	GET	ScoView
group_create	POST	ScoView
group_delete	POST	ScoView
group_edit	POST	ScoView
group_etudiants	GET	ScoView
group_etudiants_query	GET	ScoView
group_remove_etud	POST	ScoView
group_set_edt_id	POST	ScoView
group_set_etudiant	POST	ScoView
groups_get_auto_assignment	GET	ScoView
groups_save_auto_assignment	POST	ScoView
justif_create	POST	AbsChange
justif_delete	POST	AbsChange
justif_edit	POST	AbsChange
justif_export	POST	ScoView
justif_import	POST	AbsChange
justif_justifies	GET	AbsChange
justif_list	GET	ScoView
justif_remove	POST	AbsChange
justificatif	GET	ScoView
justificatifs	GET	ScoView
justificatifs_dept	GET	ScoView
justificatifs_formsemestre	GET	ScoView
logo_get_global	GET	ScoSuperAdmin
logo_get_local_dept_by_acronym	GET	ScoSuperAdmin
logo_get_local_dept_by_id	GET	ScoSuperAdmin
logo_list_globals	GET	ScoSuperAdmin
moduleimpl_evaluations	GET	ScoView
moduleimpl_inscriptions	GET	ScoView
moduleimpl_notes	GET	ScoView
partition_create	POST	ScoView
partition_delete	POST	ScoView
partition_edit	POST	ScoView
partition_info	GET	ScoView
partition_order_groups	POST	ScoView
partition_remove_etud	POST	ScoView
permissions_list	GET	UsersView
referentiel_competences	GET	ScoView
role_create	POST	ScoSuperAdmin
role_delete	POST	ScoSuperAdmin
role_edit	POST	ScoSuperAdmin
role_get	GET	UsersView
role_permission_add	POST	ScoSuperAdmin
role_permission_remove	POST	ScoSuperAdmin
roles_list	GET	UsersView
token_get	POST	Aucune permission requise
ue_assoc_niveau	POST	EditFormation
ue_desassoc_niveau	POST	EditFormation
ue_edit	POST	EditFormation
ue_set_code_apogee	POST	EditFormation
ue_set_code_apogee_rcue	POST	EditFormation
ue_set_parcours	POST	EditFormation
user_create	POST	UsersAdmin
user_edit	POST	UsersAdmin
user_info	GET	UsersView
user_password	POST	UsersAdmin
user_role_add	POST	ScoSuperAdmin
user_role_remove	POST	ScoSuperAdmin
users_info_query	GET	ScoView
validation_annee_but_delete	POST	EtudInscrit
validation_dut120_delete	POST	EtudInscrit
validation_formsemestre_delete	POST	ScoView
validation_rcue_delete	POST	EtudInscrit
validation_rcue_record	POST	EtudInscrit
validation_ue_delete	POST	ScoView

(table générée avec flask gen-api-doc)

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.

les clés sont triées (ce n'est pas toujours garanti);
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 en json '...';
les dates (au format ISO) sont systématiquement remplacées par une date fixe et ne sont pas réalistes.

API Assiduites

`assiduite`

Route: /ScoDoc/api/assiduite/<int:assiduite_id>
Méthode: GET
Permission: ScoView

Description: Retourne un objet assiduité à partir de son id

Exemple de résultat:

{
    "assiduite_id": 1,
    "etudid": 2,
    "moduleimpl_id": 3,
    "date_debut": "2022-10-31T08:00+01:00",
    "date_fin": "2022-10-31T10:00+01:00",
    "etat": "retard",
    "desc": "une description",
    "user_id": 1 or null,
    "user_name" : login scodoc or null,
    "user_nom_complet": "Marie Dupont",
    "est_just": False or True,
}

Exemple de résultat: assiduite.json

`assiduite_create`

Routes:
- /ScoDoc/api/assiduite/ine/<ine>/create
- /ScoDoc/api/assiduite/nip/<nip>/create
- /ScoDoc/api/assiduite/etudid/<int:etudid>/create
- /ScoDoc/api/assiduite/<int:etudid>/create
Méthode: POST
Permission: AbsChange
Description: Enregistrement d'assiduités pour un étudiant (etudid)
Exemple de résultat: assiduite_create.json

`assiduite_delete`

Route: /ScoDoc/api/assiduite/delete
Méthode: POST
Permission: AbsChange
Description: Suppression d'une assiduité à partir de son id
Exemple de résultat: assiduite_delete.json

`assiduite_edit`

Route: /ScoDoc/api/assiduite/<int:assiduite_id>/edit
Méthode: POST
Permission: AbsChange
Description: Edition d'une assiduité à partir de son id
Exemple de résultat: assiduite_edit.json

`assiduite_justificatifs`

Routes:
- /ScoDoc/api/assiduite/<int:assiduite_id>/justificatifs/long
- /ScoDoc/api/assiduite/<int:assiduite_id>/justificatifs
Méthode: GET
Permission: ScoView
Description: Retourne la liste des justificatifs qui justifient cette assiduité.

Exemple de résultat:
```
[
    1,
    2,
    3,
    ...
]
```
Exemple de résultat: assiduite_justificatifs.json

`assiduites(-query)`

Routes:
- /ScoDoc/api/assiduites/ine/<ine>/query
- /ScoDoc/api/assiduites/ine/<ine>
- /ScoDoc/api/assiduites/nip/<nip>/query
- /ScoDoc/api/assiduites/nip/<nip>
- /ScoDoc/api/assiduites/etudid/<int:etudid>/query
- /ScoDoc/api/assiduites/etudid/<int:etudid>
- /ScoDoc/api/assiduites/<int:etudid>/query
- /ScoDoc/api/assiduites/<int:etudid>
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur de l'assiduité
- est_just : si l'assiduité est justifiée (fait aussi filtre abs/retard)
- moduleimpl_id : l'id du module concerné par l'assiduité
- date_debut : date de début de l'assiduité (supérieur ou égal)
- date_fin : date de fin de l'assiduité (inférieur ou égal)
- etat : etat de l'étudiant → absent, present ou retard
- formsemestre_id : l'identifiant du formsemestre concerné par l'assiduité
- with_justif : ajoute les justificatifs liés à l'assiduité
Description: Retourne toutes les assiduités d'un étudiant
Exemple de résultat: assiduites.json

`assiduites_count(-query)`

Routes:
- /ScoDoc/api/assiduites/ine/<ine>/count/query
- /ScoDoc/api/assiduites/ine/<ine>/count
- /ScoDoc/api/assiduites/nip/<nip>/count/query
- /ScoDoc/api/assiduites/nip/<nip>/count
- /ScoDoc/api/assiduites/etudid/<int:etudid>/count/query
- /ScoDoc/api/assiduites/etudid/<int:etudid>/count
- /ScoDoc/api/assiduites/<int:etudid>/count/query
- /ScoDoc/api/assiduites/<int:etudid>/count
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur de l'assiduité
- est_just : si l'assiduité est justifiée (fait aussi filtre abs/retard)
- moduleimpl_id : l'id du module concerné par l'assiduité
- date_debut : date de début de l'assiduité (supérieur ou égal)
- date_fin : date de fin de l'assiduité (inférieur ou égal)
- etat : etat de l'étudiant → absent, present ou retard
- formsemestre_id : l'identifiant du formsemestre concerné par l'assiduité
- metric : la/les métriques de comptage (journee, demi, heure, compte)
- split : divise le comptage par état
Description: Retourne le nombre d'assiduités d'un étudiant.
Exemple de résultat: assiduites_count.json

`assiduites_create`

Route: /ScoDoc/api/assiduites/create
Méthode: POST
Permission: AbsChange
Description: Création d'une assiduité ou plusieurs assiduites
Exemple de résultat: assiduites_create.json

`assiduites_edit`

Route: /ScoDoc/api/assiduites/edit
Méthode: POST
Permission: AbsChange
Description: Edition de plusieurs assiduités

`assiduites_evaluations`

Routes:
- /ScoDoc/api/assiduites/nip/<nip>/evaluations
- /ScoDoc/api/assiduites/ine/<ine>/evaluations
- /ScoDoc/api/assiduites/etudid/<int:etudid>/evaluations
- /ScoDoc/api/assiduites/<int:etudid>/evaluations
Méthode: GET
Permission: ScoView

Description: Retourne la liste de toutes les évaluations de l'étudiant Pour chaque évaluation, retourne la liste des objets assiduités sur la plage de l'évaluation

Exemple de résultat:

[
    {
        "evaluation_id": 1234,
        "assiduites": [
            {
                "assiduite_id":1234,
                ...
            },
        ]
    }
]

Exemple de résultat: assiduites_evaluations.json

`assiduites_formsemestre(-query)`

Routes:
- /ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>/query
- /ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur de l'assiduité
- est_just : si l'assiduité est justifiée (fait aussi filtre abs/retard)
- moduleimpl_id : l'id du module concerné par l'assiduité
- date_debut : date de début de l'assiduité (supérieur ou égal)
- date_fin : date de fin de l'assiduité (inférieur ou égal)
- etat : etat de l'étudiant → absent, present ou retard
- formsemestre_id : l'identifiant du formsemestre concerné par l'assiduité
Description: Retourne toutes les assiduités du formsemestre
Exemple de résultat: assiduites_formsemestre.json

`assiduites_formsemestre_count(-query)`

Routes:
- /ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>/count/query
- /ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>/count
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur de l'assiduité
- est_just : si l'assiduité est justifiée (fait aussi filtre abs/retard)
- moduleimpl_id : l'id du module concerné par l'assiduité
- date_debut : date de début de l'assiduité (supérieur ou égal)
- date_fin : date de fin de l'assiduité (inférieur ou égal)
- etat : etat de l'étudiant → absent, present ou retard
- formsemestre_id : l'identifiant du formsemestre concerné par l'assiduité
- metric : la/les métriques de comptage (journee, demi, heure, compte)
- split : divise le comptage par état
Description: Comptage des assiduités du formsemestre
Exemple de résultat: assiduites_formsemestre_count.json

`assiduites_group(-query)`

Route: /ScoDoc/api/assiduites/group/query
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur de l'assiduité
- est_just : si l'assiduité est justifiée (fait aussi filtre abs/retard)
- moduleimpl_id : l'id du module concerné par l'assiduité
- date_debut : date de début de l'assiduité (supérieur ou égal)
- date_fin : date de fin de l'assiduité (inférieur ou égal)
- etat : etat de l'étudiant → absent, present ou retard
- etudids : liste des ids des étudiants concernés par la recherche
- formsemestre_id : l'identifiant du formsemestre concerné par l'assiduité
- with_justifs : ajoute les justificatifs liés à l'assiduité
Description: Retourne toutes les assiduités d'un groupe d'étudiants chemin : /assiduites/group/query?etudids=1,2,3
Exemple de résultat: assiduites_group.json

API Billets d'absence

`billets_absence_create`

Route: /ScoDoc/api/billets_absence/create
Méthode: POST
Permission: Aucune permission requise
Description: Ajout d'un billet d'absence. Renvoie le billet créé en json.
Exemple de résultat: billets_absence_create.json

`billets_absence_delete`

Route: /ScoDoc/api/billets_absence/<int:billet_id>/delete
Méthode: POST
Permission: Aucune permission requise
Description: Suppression d'un billet d'absence

`billets_absence_etudiant`

Route: /ScoDoc/api/billets_absence/etudiant/<int:etudid>
Méthode: GET
Permission: Aucune permission requise
Description: Liste des billets d'absence pour cet étudiant.

API Département

`departement_by_acronym`

Route: /ScoDoc/api/departement/<string:acronym>
Méthode: GET
Permission: ScoView
Description: Info sur un département. Accès par acronyme.
Exemple de résultat: departement_by_acronym.json

`departement_create`

Route: /ScoDoc/api/departement/create
Méthode: POST
Permission: ScoSuperAdmin
Description: Création d'un département. Le content type doit être application/json.
Exemple de résultat: departement_create.json

`departement_delete`

Route: /ScoDoc/api/departement/<string:acronym>/delete
Méthode: POST
Permission: ScoSuperAdmin
Description: Suppression d'un département identifié par son acronyme.

`departement_edit`

Route: /ScoDoc/api/departement/<string:acronym>/edit
Méthode: POST
Permission: ScoSuperAdmin
Description: Édition d'un département: seul le champ visible peut être modifié.

`departement_etudiants`

Route: /ScoDoc/api/departement/<string:acronym>/etudiants
Méthode: GET
Permission: ScoView
Paramètres:
- acronym : l'acronyme d'un département
Description: Retourne la liste des étudiants d'un département.
Exemple de résultat: departement_etudiants.json

`departement_etudiants_by_id`

Route: /ScoDoc/api/departement/id/<int:dept_id>/etudiants
Méthode: GET
Permission: ScoView
Description: Retourne la liste des étudiants d'un département d'id donné.

`departement_formsemestres_courants(-query)`

Routes:
- /ScoDoc/api/departement/id/<int:dept_id>/formsemestres_courants
- /ScoDoc/api/departement/<string:acronym>/formsemestres_courants
Méthode: GET
Permission: ScoView
Description: Liste les formsemestres du département indiqué (par son acronyme ou son id) contenant la date courante, ou à défaut celle indiquée en argument (au format ISO).
Exemple de résultat: departement_formsemestres_courants.json

`departement_formsemestres_ids`

Route: /ScoDoc/api/departement/<string:acronym>/formsemestres_ids
Méthode: GET
Permission: ScoView
Description: Liste des ids de tous les formsemestres du département.
Exemple de résultat: departement_formsemestres_ids.json

`departement_formsemestres_ids_by_id`

Route: /ScoDoc/api/departement/id/<int:dept_id>/formsemestres_ids
Méthode: GET
Permission: ScoView
Description: Liste des ids de tous les formsemestres du département.
Exemple de résultat: departement_formsemestres_ids_by_id.json

`departement_get`

Route: /ScoDoc/api/departement/id/<int:dept_id>
Méthode: GET
Permission: ScoView
Description: Info sur un département. Accès par id.
Exemple de résultat: departement_get.json

`departements_ids`

Route: /ScoDoc/api/departements_ids
Méthode: GET
Permission: ScoView
Description: Liste des ids de tous les départements.
Exemple de résultat: departements_ids.json

`departements_list`

Route: /ScoDoc/api/departements
Méthode: GET
Permission: ScoView
Description: Liste tous les départements.
Exemple de résultat: departements_list.json

API Étudiants

`bulletin`

Routes:
- /ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin/<string:version>/pdf/nosig
- /ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin/<string:version>/pdf
- /ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin/<string:version>
- /ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin
Méthode: GET
Permission: ScoView
Paramètres:
- formsemestre_id : l'id d'un formsemestre
- code_type : "etudid", "nip" ou "ine"
- code : valeur du code INE, NIP ou etudid, selon code_type.
- version : type de bulletin (par défaut, "selectedevals"): short, long, selectedevals, butcourt
- pdf : si spécifié, bulletin au format PDF (et non JSON).
Description: Retourne le bulletin d'un étudiant dans un formsemestre.
Exemple de résultat: bulletin.json

`etudiant`

Routes:
- /ScoDoc/api/etudiant/ine/<string:ine>
- /ScoDoc/api/etudiant/nip/<string:nip>
- /ScoDoc/api/etudiant/etudid/<int:etudid>
Méthode: GET
Permission: ScoView
Paramètres:
- etudid : l'etudid de l'étudiant
- nip : le code nip de l'étudiant
- ine : le code ine de l'étudiant
Description: Retourne les informations de l'étudiant correspondant, ou 404 si non trouvé.

etudid est unique dans la base (tous départements). Les codes INE et NIP sont uniques au sein d'un département. Si plusieurs objets ont le même code, on ramène le plus récemment inscrit.

`etudiant_annotation`

Route: /ScoDoc/api/etudiant/<string:code_type>/<string:code>/annotation
Méthode: POST
Permission: EtudInscrit
Paramètres:
- code_type : le type du code, etudid, ine ou nip.
- code : la valeur du code
Description: Ajout d'une annotation sur un étudiant.

Renvoie l'annotation créée.
Exemple de résultat: etudiant_annotation.json

`etudiant_annotation_delete`

Route: /ScoDoc/api/etudiant/<string:code_type>/<string:code>/annotation/<int:annotation_id>/delete
Méthode: POST
Permission: EtudInscrit
Paramètres:
- code_type : le type du code, etudid, ine ou nip.
- code : la valeur du code
- annotation_id : id de l'annotation
Description: Suppression d'une annotation. On spécifie l'étudiant et l'id de l'annotation.

`etudiant_create`

Routes:
- /ScoDoc/api/etudiant/create/force
- /ScoDoc/api/etudiant/create
Méthode: POST
Permission: EtudInscrit
Description: Création d'un nouvel étudiant.

Si force, crée même si homonymie détectée.

L'étudiant créé n'est pas inscrit à un semestre.

Champs requis: nom, prenom (sauf si config sans prénom), dept (string:acronyme)

`etudiant_edit`

Route: /ScoDoc/api/etudiant/<string:code_type>/<string:code>/edit
Méthode: POST
Permission: EtudInscrit
Paramètres:
- code_type : le type du code, etudid, ine ou nip.
- code : la valeur du code
Description: Édition des données étudiant (identité, admission, adresses).
Exemple de résultat: etudiant_edit.json

`etudiant_formsemestres`

Routes:
- /ScoDoc/api/etudiant/ine/<string:ine>/formsemestres
- /ScoDoc/api/etudiant/nip/<string:nip>/formsemestres
- /ScoDoc/api/etudiant/etudid/<int:etudid>/formsemestres
Méthode: GET
Permission: ScoView
Description: Liste des formsemestres qu'un étudiant a suivi, triés par ordre chronologique. Accès par etudid, nip ou ine.

Attention, si accès via NIP ou INE, les formsemestres peuvent être de départements différents (si l'étudiant a changé de département). L'id du département est dept_id.

Si accès par département, ne retourne que les formsemestres suivis dans le département.

`etudiant_get_photo_image(-query)`

Routes:
- /ScoDoc/api/etudiant/ine/<string:ine>/photo
- /ScoDoc/api/etudiant/nip/<string:nip>/photo
- /ScoDoc/api/etudiant/etudid/<int:etudid>/photo
Méthode: GET
Permission: ScoView
Paramètres:
- etudid : l'etudid de l'étudiant
- nip : le code nip de l'étudiant
- ine : le code ine de l'étudiant
Description: Retourne la photo de l'étudiant ou un placeholder si non existant. Le paramètre size peut prendre la valeur small (taille réduite, hauteur environ 90 pixels) ou orig (défaut, image de la taille originale).

`etudiant_groups`

Route: /ScoDoc/api/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/groups
Méthode: GET
Permission: ScoView
Paramètres:
- formsemestre_id : l'id d'un formsemestre
- etudid : l'etudid d'un étudiant
Description: Retourne la liste des groupes auxquels appartient l'étudiant dans le formsemestre indiqué
Exemple de résultat: etudiant_groups.json

`etudiants`

Routes:
- /ScoDoc/api/etudiants/ine/<string:ine>
- /ScoDoc/api/etudiants/nip/<string:nip>
- /ScoDoc/api/etudiants/etudid/<int:etudid>
Méthode: GET
Permission: ScoView
Description: 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.).

`etudiants_by_name`

Route: /ScoDoc/api/etudiants/name/<string:start>
Méthode: GET
Permission: ScoView
Description: Liste des étudiants dont le nom débute par start.

Si start fait moins de min_len=3 caractères, liste vide. La casse et les accents sont ignorés.

`etudiants_courants(-query)`

Routes:
- /ScoDoc/api/etudiants/courants/long
- /ScoDoc/api/etudiants/courants
Méthode: GET
Permission: ScoView
Description: La liste des étudiants des semestres "courants". Considère tous les départements dans lesquels l'utilisateur a la permission ScoView (donc tous si le dépt. du rôle est None), et les formsemestres contenant la date courante, ou à défaut celle indiquée en argument (au format ISO).

En format "long": voir l'exemple.
Exemple de résultat: etudiants_courants.json

API Évaluations

`evaluation_assiduites`

Route: /ScoDoc/api/evaluation/<int:evaluation_id>/assiduites
Méthode: GET
Permission: ScoView

Description: Retourne les objets assiduités de chaque étudiant sur la plage de l'évaluation

Exemple de résultat:

{
    "<etudid>" : [
        {
            "assiduite_id":1234,
            ...
        },
    ]
}

`evaluation_create`

Route: /ScoDoc/api/moduleimpl/<int:moduleimpl_id>/evaluation/create
Méthode: POST
Permission: EnsView
Description: Création d'une évaluation.

Résultat: l'évaluation créée.
Exemple de résultat: evaluation_create.json

`evaluation_delete`

Route: /ScoDoc/api/evaluation/<int:evaluation_id>/delete
Méthode: POST
Permission: EnsView
Description: Suppression d'une évaluation. Efface aussi toutes ses notes.

`evaluation_notes`

Route: /ScoDoc/api/evaluation/<int:evaluation_id>/notes
Méthode: GET
Permission: ScoView
Paramètres:
- evaluation_id : l'id de l'évaluation
Description: Retourne la liste des notes de l'évaluation.
Exemple de résultat: evaluation_notes.json

`evaluation_set_notes`

Route: /ScoDoc/api/evaluation/<int:evaluation_id>/notes/set
Méthode: POST
Permission: EnsView
Description: Écriture de notes dans une évaluation.

Résultat:
- etudids_changed: étudiants dont la note est modifiée
- etudids_with_decision: liste des etudiants dont la note a changé alors qu'ils ont une décision de jury enregistrée.
- history_menu: un fragment de HTML expliquant l'historique de la note de chaque étudiant modifié.
Exemple de résultat: evaluation_set_notes.json

`moduleimpl_evaluations`

Route: /ScoDoc/api/moduleimpl/<int:moduleimpl_id>/evaluations
Méthode: GET
Permission: ScoView
Paramètres:
- moduleimpl_id : l'id d'un moduleimpl
Description: Retourne la liste des évaluations d'un moduleimpl.
Exemple de résultat: moduleimpl_evaluations.json

API Formations

`formation_export_by_formation_id`

Routes:
- /ScoDoc/api/formation/<int:formation_id>/export_with_ids
- /ScoDoc/api/formation/<int:formation_id>/export
Méthode: GET
Permission: ScoView
Paramètres:
- formation_id : l'id d'une formation
- export_with_ids : si présent, exporte aussi les ids des objets ScoDoc de la formation.
Description: Retourne la formation, avec UE, matières, modules
Exemple de résultat: formation_export_by_formation_id.json

`formation_get`

Route: /ScoDoc/api/formation/<int:formation_id>
Méthode: GET
Permission: ScoView
Description: La formation d'id donné.
Exemple de résultat: formation_get.json

`formation_module_edit`

Route: /ScoDoc/api/formation/module/<int:module_id>/edit
Méthode: POST
Permission: EditFormation
Description: Édition d'un module. Renvoie le module en json.

`formation_module_get`

Route: /ScoDoc/api/formation/module/<int:module_id>
Méthode: GET
Permission: ScoView
Description: Renvoie le module.
Exemple de résultat: formation_module_get.json

`formation_module_set_code_apogee`

Routes:
- /ScoDoc/api/formation/module/<int:module_id>/set_code_apogee
- /ScoDoc/api/formation/module/<int:module_id>/set_code_apogee/<string:code_apogee>
- /ScoDoc/api/formation/module/set_code_apogee
Méthode: POST
Permission: EditFormation
Description: Change le code Apogée du module.

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur formation verrouillée.

Si module_id n'est pas spécifié, utilise l'argument oid du POST. Si code_apogee n'est pas spécifié ou vide, utilise l'argument value du POST (utilisé par jinplace.js)

Le retour est une chaîne (le code enregistré), pas du json.

`formations`

Route: /ScoDoc/api/formations
Méthode: GET
Permission: ScoView
Description: Retourne la liste de toutes les formations (tous départements, sauf si route départementale).
Exemple de résultat: formations.json

`formations_ids`

Route: /ScoDoc/api/formations_ids
Méthode: GET
Permission: ScoView
Description: Retourne la liste de toutes les id de formations (tous départements, ou du département indiqué dans la route)

Exemple de résultat : [ 17, 99, 32 ].
Exemple de résultat: formations_ids.json

`referentiel_competences`

Route: /ScoDoc/api/formation/<int:formation_id>/referentiel_competences
Méthode: GET
Permission: ScoView
Description: Retourne le référentiel de compétences de la formation ou null si pas de référentiel associé.
Exemple de résultat: referentiel_competences.json

`ue_assoc_niveau`

Route: /ScoDoc/api/formation/ue/<int:ue_id>/assoc_niveau/<int:niveau_id>
Méthode: POST
Permission: EditFormation
Description: Associe l'UE au niveau de compétence.

`ue_desassoc_niveau`

Route: /ScoDoc/api/formation/ue/<int:ue_id>/desassoc_niveau
Méthode: POST
Permission: EditFormation
Description: Désassocie cette UE de son niveau de compétence (si elle n'est pas associée, ne fait rien).

`ue_edit`

Route: /ScoDoc/api/formation/ue/<int:ue_id>/edit
Méthode: POST
Permission: EditFormation
Description: Édition d'une UE. Renvoie l'UE en json.

`ue_set_code_apogee`

Routes:
- /ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee
- /ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee/<string:code_apogee>
- /ScoDoc/api/formation/ue/set_code_apogee
Méthode: POST
Permission: EditFormation
Description: Change le code Apogée de l'UE.

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur formation verrouillée.

Si ue_id n'est pas spécifié, utilise l'argument oid du POST. Si code_apogee n'est pas spécifié ou vide, utilise l'argument value du POST.

Le retour est une chaîne (le code enregistré), pas du json.

`ue_set_code_apogee_rcue`

Routes:
- /ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee_rcue
- /ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee_rcue/<string:code_apogee>
Méthode: POST
Permission: EditFormation
Description: Change le code Apogée du RCUE de l'UE.

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur formation verrouillée.

Si code_apogee n'est pas spécifié ou vide, utilise l'argument value du POST (utilisé par jinplace.js)

Le retour est une chaîne (le code enregistré), pas du json.

`ue_set_parcours`

Route: /ScoDoc/api/formation/ue/<int:ue_id>/set_parcours
Méthode: POST
Permission: EditFormation
Description: Associe UE et parcours BUT.

La liste des ids de parcours est passée en argument JSON.

API Formsemestre

`bulletins`

Routes:
- /ScoDoc/api/formsemestre/<int:formsemestre_id>/bulletins/<string:version>
- /ScoDoc/api/formsemestre/<int:formsemestre_id>/bulletins
Méthode: GET
Permission: ScoView
Paramètres:
- formsemestre_id : int
- version : string ("long", "short", "selectedevals")
Description: Retourne les bulletins d'un formsemestre.
Exemple de résultat: bulletins.json

`formsemestre_edit`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/edit
Méthode: POST
Permission: EditFormSemestre
Description: Modifie les champs d'un formsemestre.

On peut spécifier un ou plusieurs champs.

`formsemestre_edt(-query)`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/edt
Méthode: GET
Permission: ScoView
Description: L'emploi du temps du semestre.

Si ok, une liste d'évènements. Sinon, une chaine indiquant un message d'erreur.

Expérimental, ne pas utiliser hors ScoDoc.

`formsemestre_etat_evaluations`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/etat_evals
Méthode: GET
Permission: ScoView
Description: Informations sur l'état des évaluations d'un formsemestre.
Exemple de résultat: formsemestre_etat_evaluations.json

`formsemestre_etudiants(-query)`

Routes:
- /ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants/long/query
- /ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants/query
- /ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants/long
- /ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants
Méthode: GET
Permission: ScoView
Description: Étudiants d'un formsemestre.

Si l'état est spécifié, ne renvoie que les inscrits (I), les démissionnaires (D) ou les défaillants (DEF)
Exemple de résultat: formsemestre_etudiants.json

`formsemestre_get`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>
Méthode: GET
Permission: ScoView
Description: Information sur le formsemestre indiqué.

formsemestre_id : l'id du formsemestre
Exemple de résultat: formsemestre_get.json

`formsemestre_programme`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/programme
Méthode: GET
Permission: ScoView
Description: Retourne la liste des UEs, ressources et SAEs d'un semestre
Exemple de résultat: formsemestre_programme.json

`formsemestre_resultat(-query)`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/resultats
Méthode: GET
Permission: ScoView
Description: Tableau récapitulatif des résultats.

Pour chaque étudiant, son état, ses groupes, ses moyennes d'UE et de modules.

Si format=raw, ne converti pas les valeurs.
Exemple de résultat: formsemestre_resultat.json

`formsemestre_set_apo_etapes`

Route: /ScoDoc/api/formsemestre/apo/set_etapes
Méthode: POST
Permission: EditApogee
Description: Change les codes étapes du semestre indiqué.

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur un semestre verrouillé.

`formsemestre_set_elt_annee_apo`

Route: /ScoDoc/api/formsemestre/apo/set_elt_annee
Méthode: POST
Permission: EditApogee
Description: Change les codes étapes du semestre indiqué (par le champ oid).

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur un semestre verrouillé.

`formsemestre_set_elt_passage_apo`

Route: /ScoDoc/api/formsemestre/apo/set_elt_passage
Méthode: POST
Permission: EditApogee
Description: Change les codes Apogée de passage du semestre indiqué (par le champ oid).

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur un semestre verrouillé.

`formsemestre_set_elt_sem_apo`

Route: /ScoDoc/api/formsemestre/apo/set_elt_sem
Méthode: POST
Permission: EditApogee
Description: Change les codes étapes du semestre indiqué.

Le code est une chaîne, avec éventuellement plusieurs valeurs séparées par des virgules.

Ce changement peut être fait sur un semestre verrouillé.

`formsemestres_query(-query)`

Route: /ScoDoc/api/formsemestres/query
Méthode: GET
Permission: ScoView
Paramètres:
- etape_apo : un code étape apogée
- annee_scolaire : année de début de l'année scolaire
- dept_acronym : acronyme du département (eg "RT")
- dept_id : id du département
- ine ou nip : code d'un étudiant: ramène alors tous les semestres auxquels il est inscrit.
- etat : 0 si verrouillé, 1 sinon
Description: Retourne les formsemestres filtrés par étape Apogée ou année scolaire ou département (acronyme ou id) ou état ou code étudiant.

`groups_get_auto_assignment`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/groups_get_auto_assignment
Méthode: GET
Permission: ScoView
Description: Rend les données stockées par groups_save_auto_assignment.

`groups_save_auto_assignment`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/groups_save_auto_assignment
Méthode: POST
Permission: ScoView
Description: Enregistre les données, associées à ce formsemestre. Usage réservé aux fonctions de gestion des groupes, ne pas utiliser ailleurs.

API Groupes et partitions

`formsemestre_partitions`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/partitions
Méthode: GET
Permission: ScoView
Description: Liste de toutes les partitions d'un formsemestre.
Exemple de résultat: formsemestre_partitions.json

`formsemestre_set_partitions_order`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/partitions/order
Méthode: POST
Permission: ScoView
Description: Modifie l'ordre des partitions du formsemestre.

`group_create`

Route: /ScoDoc/api/partition/<int:partition_id>/group/create
Méthode: POST
Permission: ScoView
Description: Création d'un groupe dans une partition.
Exemple de résultat: group_create.json

`group_delete`

Route: /ScoDoc/api/group/<int:group_id>/delete
Méthode: POST
Permission: ScoView
Description: Suppression d'un groupe.

`group_edit`

Route: /ScoDoc/api/group/<int:group_id>/edit
Méthode: POST
Permission: ScoView
Description: Édition d'un groupe.
Exemple de résultat: group_edit.json

`group_etudiants`

Route: /ScoDoc/api/group/<int:group_id>/etudiants
Méthode: GET
Permission: ScoView
Paramètres:
- group_id : l'id d'un groupe
Description: Retourne la liste des étudiants dans un groupe (inscrits au groupe et inscrits au semestre).
Exemple de résultat: group_etudiants.json

`group_etudiants_query(-query)`

Route: /ScoDoc/api/group/<int:group_id>/etudiants/query
Méthode: GET
Permission: ScoView
Description: Étudiants du groupe, filtrés par état (aucun, I, D, DEF)

`group_remove_etud`

Route: /ScoDoc/api/group/<int:group_id>/remove_etudiant/<int:etudid>
Méthode: POST
Permission: ScoView
Description: Retire l'étudiant de ce groupe. S'il n'y est pas, ne fait rien.

`group_set_edt_id`

Route: /ScoDoc/api/group/<int:group_id>/set_edt_id/<string:edt_id>
Méthode: POST
Permission: ScoView
Description: Set edt_id du groupe.

Contrairement à /edit, peut-être changé pour toute partition d'un formsemestre non verrouillé.
Exemple de résultat: group_set_edt_id.json

`group_set_etudiant`

Route: /ScoDoc/api/group/<int:group_id>/set_etudiant/<int:etudid>
Méthode: POST
Permission: ScoView
Description: Affecte l'étudiant au groupe indiqué.

`partition_create`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/partition/create
Méthode: POST
Permission: ScoView
Description: Création d'une partition dans un semestre.

`partition_delete`

Route: /ScoDoc/api/partition/<int:partition_id>/delete
Méthode: POST
Permission: ScoView
Description: Suppression d'une partition (et de tous ses groupes).
- Note 1: La partition par défaut (tous les étudiants du sem.) ne peut pas être supprimée.
- Note 2: Si la partition de parcours est supprimée, les étudiants sont désinscrits des parcours.

`partition_edit`

Route: /ScoDoc/api/partition/<int:partition_id>/edit
Méthode: POST
Permission: ScoView
Description: Modification d'une partition dans un semestre.

Tous les champs sont optionnels.
Exemple de résultat: partition_edit.json

`partition_info`

Route: /ScoDoc/api/partition/<int:partition_id>
Méthode: GET
Permission: ScoView
Description: Info sur une partition.
Exemple de résultat: partition_info.json

`partition_order_groups`

Route: /ScoDoc/api/partition/<int:partition_id>/groups/order
Méthode: POST
Permission: ScoView
Description: Modifie l'ordre des groupes de la partition.

`partition_remove_etud`

Route: /ScoDoc/api/partition/<int:partition_id>/remove_etudiant/<int:etudid>
Méthode: POST
Permission: ScoView
Description: Enlève l'étudiant de tous les groupes de cette partition.

(NB: en principe, un étudiant ne doit être que dans 0 ou 1 groupe d'une partition)

API Jury

`autorisation_inscription_delete`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/autorisation_inscription/<int:validation_id>/delete
Méthode: POST
Permission: EtudInscrit
Description: Efface cette autorisation d'inscription.

`decisions_jury`

Route: /ScoDoc/api/formsemestre/<int:formsemestre_id>/decisions_jury
Méthode: GET
Permission: ScoView
Description: Décisions du jury des étudiants du formsemestre.
Exemple de résultat: decisions_jury.json

`validation_annee_but_delete`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/validation_annee_but/<int:validation_id>/delete
Méthode: POST
Permission: EtudInscrit
Description: Efface cette validation d'année BUT.

`validation_dut120_delete`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/validation_dut120/<int:validation_id>/delete
Méthode: POST
Permission: EtudInscrit
Description: Efface cette validation de DUT120.

`validation_formsemestre_delete`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/validation_formsemestre/<int:validation_id>/delete
Méthode: POST
Permission: ScoView
Description: Efface cette validation de semestre.

`validation_rcue_delete`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/validation_rcue/<int:validation_id>/delete
Méthode: POST
Permission: EtudInscrit
Description: Efface cette validation de RCUE.

`validation_rcue_record`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/validation_rcue/record
Méthode: POST
Permission: EtudInscrit
Description: Enregistre une validation de RCUE.

Si une validation existe déjà pour ce RCUE, la remplace.

`validation_ue_delete`

Route: /ScoDoc/api/etudiant/<int:etudid>/jury/validation_ue/<int:validation_id>/delete
Méthode: POST
Permission: ScoView
Description: Efface cette validation d'UE.

API Justificatifs

`justif_create`

Routes:
- /ScoDoc/api/justificatif/ine/<ine>/create
- /ScoDoc/api/justificatif/nip/<nip>/create
- /ScoDoc/api/justificatif/etudid/<int:etudid>/create
- /ScoDoc/api/justificatif/<int:etudid>/create
Méthode: POST
Permission: AbsChange
Description: Création d'un justificatif pour l'étudiant.

`justif_delete`

Route: /ScoDoc/api/justificatif/delete
Méthode: POST
Permission: AbsChange
Description: Suppression d'un justificatif à partir de son id.
Exemple de résultat: justif_delete.json

`justif_edit`

Route: /ScoDoc/api/justificatif/<int:justif_id>/edit
Méthode: POST
Permission: AbsChange
Description: Édition d'un justificatif à partir de son id.
Exemple de résultat: justif_edit.json

`justif_export`

Route: /ScoDoc/api/justificatif/<int:justif_id>/export/<filename>
Méthode: POST
Permission: ScoView
Description: Retourne un fichier d'une archive d'un justificatif.

La permission est ScoView + (AbsJustifView ou être l'auteur du justificatif).

Procédure de téléchargement de fichier : télécharger un justificatif

`justif_import`

Route: /ScoDoc/api/justificatif/<int:justif_id>/import
Méthode: POST
Permission: AbsChange
Description: Importation d'un fichier (création d'archive).

Procédure d'importation de fichier : importer un justificatif

`justif_justifies`

Route: /ScoDoc/api/justificatif/<int:justif_id>/justifies
Méthode: GET
Permission: AbsChange
Description: Liste assiduite_id justifiées par le justificatif.
Exemple de résultat: justif_justifies.json

`justif_list`

Route: /ScoDoc/api/justificatif/<int:justif_id>/list
Méthode: GET
Permission: ScoView
Description: Liste les fichiers du justificatif.
Exemple de résultat: justif_list.json

`justif_remove`

Route: /ScoDoc/api/justificatif/<int:justif_id>/remove
Méthode: POST
Permission: AbsChange
Description: Supression d'un fichier ou d'une archive.

Procédure de suppression de fichier : supprimer un justificatif

`justificatif`

Route: /ScoDoc/api/justificatif/<int:justif_id>
Méthode: GET
Permission: ScoView

Description: Retourne un objet justificatif à partir de son id.

Exemple de résultat:

{
    "justif_id": 1,
    "etudid": 2,
    "date_debut": "2022-10-31T08:00+01:00",
    "date_fin": "2022-10-31T10:00+01:00",
    "etat": "valide",
    "fichier": "archive_id",
    "raison": "une raison", // VIDE si pas le droit
    "entry_date": "2022-10-31T08:00+01:00",
    "user_id": 1 or null,
}

Exemple de résultat: justificatif.json

`justificatifs(-query)`

Routes:
- /ScoDoc/api/justificatifs/ine/<ine>/query
- /ScoDoc/api/justificatifs/ine/<ine>
- /ScoDoc/api/justificatifs/nip/<nip>/query
- /ScoDoc/api/justificatifs/nip/<nip>
- /ScoDoc/api/justificatifs/etudid/<int:etudid>/query
- /ScoDoc/api/justificatifs/etudid/<int:etudid>
- /ScoDoc/api/justificatifs/<int:etudid>/query
- /ScoDoc/api/justificatifs/<int:etudid>
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur du justificatif
- date_debut : date de début du justificatif (supérieur ou égal)
- date_fin : date de fin du justificatif (inférieur ou égal)
- etat : etat du justificatif → valide, non_valide, attente, modifie
- order : retourne les justificatifs dans l'ordre décroissant (non vide = True)
- courant : retourne les justificatifs de l'année courante (bool : v/t ou f)
- group_id : int:group_id
Description: Retourne toutes les assiduités d'un étudiant
Exemple de résultat: justificatifs.json

`justificatifs_dept(-query)`

Routes:
- /ScoDoc/api/justificatifs/dept/<int:dept_id>/query
- /ScoDoc/api/justificatifs/dept/<int:dept_id>
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur du justificatif
- date_debut : date de début du justificatif (supérieur ou égal)
- date_fin : date de fin du justificatif (inférieur ou égal)
- etat : etat du justificatif → valide, non_valide, attente, modifie
- order : retourne les justificatifs dans l'ordre décroissant (non vide = True)
- courant : retourne les justificatifs de l'année courante (bool : v/t ou f)
- group_id : int:group_id
Description: Renvoie tous les justificatifs d'un département (en ajoutant un champ "formsemestre" si possible).
Exemple de résultat: justificatifs_dept.json

`justificatifs_formsemestre(-query)`

Routes:
- /ScoDoc/api/justificatifs/formsemestre/<int:formsemestre_id>/query
- /ScoDoc/api/justificatifs/formsemestre/<int:formsemestre_id>
Méthode: GET
Permission: ScoView
Paramètres:
- user_id : l'id de l'auteur du justificatif
- date_debut : date de début du justificatif (supérieur ou égal)
- date_fin : date de fin du justificatif (inférieur ou égal)
- etat : etat du justificatif → valide, non_valide, attente, modifie
- order : retourne les justificatifs dans l'ordre décroissant (non vide = True)
- courant : retourne les justificatifs de l'année courante (bool : v/t ou f)
- group_id : int:group_id
Description: Retourne tous les justificatifs du formsemestre.
Exemple de résultat: justificatifs_formsemestre.json

API Logos

`departement_logos`

Route: /ScoDoc/api/departement/<string:dept_acronym>/logos
Méthode: GET
Permission: ScoSuperAdmin
Description: Liste des noms des logos définis pour le département désigné par son acronyme.
Exemple de résultat: departement_logos.json

`departement_logos_by_id`

Route: /ScoDoc/api/departement/id/<int:dept_id>/logos
Méthode: GET
Permission: ScoSuperAdmin
Description: Liste des noms des logos définis pour le département désigné par son id.

`logo_get_global`

Route: /ScoDoc/api/logo/<string:logoname>
Méthode: GET
Permission: ScoSuperAdmin
Description: Renvoie le logo global de nom donné.

L'image est au 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_get_global.json

`logo_get_local_dept_by_acronym`

Route: /ScoDoc/api/departement/<string:departement>/logo/<string:logoname>
Méthode: GET
Permission: ScoSuperAdmin
Description: Le logo: image (format png ou jpg).

Exemple d'utilisation:
```
  * `/ScoDoc/api/departement/MMI/logo/header`
```

`logo_get_local_dept_by_id`

Route: /ScoDoc/api/departement/id/<int:dept_id>/logo/<string:logoname>
Méthode: GET
Permission: ScoSuperAdmin
Description: Le logo: image (format png ou jpg).

Exemple d'utilisation:
```
      * `/ScoDoc/api/departement/id/3/logo/header`
```

`logo_list_globals`

Route: /ScoDoc/api/logos
Méthode: GET
Permission: ScoSuperAdmin
Description: Liste des noms des logos définis pour le site ScoDoc.
Exemple de résultat: logo_list_globals.json

API Moduleimpl

`moduleimpl_inscriptions`

Route: /ScoDoc/api/moduleimpl/<int:moduleimpl_id>/inscriptions
Méthode: GET
Permission: ScoView
Description: Liste des inscriptions à ce moduleimpl.
Exemple de résultat: moduleimpl_inscriptions.json

`moduleimpl_notes`

Route: /ScoDoc/api/moduleimpl/<int:moduleimpl_id>/notes
Méthode: GET
Permission: ScoView
Description: Liste des notes dans ce moduleimpl.
Exemple de résultat: moduleimpl_notes.json

API Tokens

`token_get`

Route: /ScoDoc/api/tokens
Méthode: POST
Permission: Aucune permission requise
Description: Renvoie un jeton jwt pour l'utilisateur courant.

API Utilisateurs

`permissions_list`

Route: /ScoDoc/api/permissions
Méthode: GET
Permission: UsersView
Description: Liste des noms de permissions définies.
Exemple de résultat: permissions_list.json

`role_create`

Route: /ScoDoc/api/role/create/<string:role_name>
Méthode: POST
Permission: ScoSuperAdmin
Description: Création d'un nouveau rôle avec les permissions données.
Exemple de résultat: role_create.json

`role_delete`

Route: /ScoDoc/api/role/<string:role_name>/delete
Méthode: POST
Permission: ScoSuperAdmin
Description: Suppression d'un rôle.
Exemple de résultat: role_delete.json

`role_edit`

Route: /ScoDoc/api/role/<string:role_name>/edit
Méthode: POST
Permission: ScoSuperAdmin
Description: Édition d'un rôle. On peut spécifier un nom et/ou des permissions.

`role_get`

Route: /ScoDoc/api/role/<string:role_name>
Méthode: GET
Permission: UsersView
Description: Un rôle.
Exemple de résultat: role_get.json

`role_permission_add`

Route: /ScoDoc/api/role/<string:role_name>/add_permission/<string:perm_name>
Méthode: POST
Permission: ScoSuperAdmin
Description: Ajoute une permission à un rôle.

`role_permission_remove`

Route: /ScoDoc/api/role/<string:role_name>/remove_permission/<string:perm_name>
Méthode: POST
Permission: ScoSuperAdmin
Description: Retire une permission d'un rôle.

`roles_list`

Route: /ScoDoc/api/roles
Méthode: GET
Permission: UsersView
Description: Tous les rôles définis.
Exemple de résultat: roles_list.json

`user_create`

Route: /ScoDoc/api/user/create
Méthode: POST
Permission: UsersAdmin
Description: Création d'un utilisateur

`user_edit`

Route: /ScoDoc/api/user/<int:uid>/edit
Méthode: POST
Permission: UsersAdmin

Description: Modification d'un utilisateur.

Champs modifiables:

{
    "dept": str or null,
    "nom": str,
    "prenom": str,
    "active":bool
    ...
}

`user_info`

Route: /ScoDoc/api/user/<int:uid>
Méthode: GET
Permission: UsersView
Description: Info sur un compte utilisateur ScoDoc.
Exemple de résultat: user_info.json

`user_password`

Route: /ScoDoc/api/user/<int:uid>/password
Méthode: POST
Permission: UsersAdmin
Description: Modification du mot de passe d'un utilisateur.

Si le mot de passe ne convient pas, erreur 400.
Exemple de résultat: user_password.json

`user_role_add`

Routes:
- /ScoDoc/api/user/<int:uid>/role/<string:role_name>/add/departement/<string:dept>
- /ScoDoc/api/user/<int:uid>/role/<string:role_name>/add
Méthode: POST
Permission: ScoSuperAdmin
Description: Ajoute un rôle à l'utilisateur dans le département donné.

`user_role_remove`

Routes:
- /ScoDoc/api/user/<int:uid>/role/<string:role_name>/remove/departement/<string:dept>
- /ScoDoc/api/user/<int:uid>/role/<string:role_name>/remove
Méthode: POST
Permission: ScoSuperAdmin
Description: Retire le rôle (dans le département donné) à cet utilisateur.

`users_info_query(-query)`

Route: /ScoDoc/api/users/query
Méthode: GET
Permission: ScoView
Description: Utilisateurs, filtrés par dept, active ou début nom

Exemple:
```
/users/query?departement=dept_acronym&active=1&starts_with=<string:nom>
```
Seuls les utilisateurs "accessibles" (selon les permissions) sont retournés. Si accès via API web, le département de l'URL est ignoré, seules les permissions de l'utilisateur sont prises en compte.

En savoir plus

Voir exemples d'utilisation de l'API en Python, dans tests/api/.

!!! note "Voir aussi"

- [Guide configuration et ligne de commande](GuideConfig.md)
- [Guide administrateur ScoDoc](GuideAdminSys.md)
- [ServicesXml](ServicesXml.md) : anciens web services XML (obsolète)
- [FAQ](FAQ.md)
- [Contacts](Contact.md)

73 KiB Raw Blame History

API pour ScoDoc 9

Configuration de ScoDoc pour utiliser l'API

Essais avec HTTPie

Fonctions d'API ScoDoc 9

Accès à l'API REST

Authentification

Codes HTTP

Règles générales

Référence

Carte syntaxique

Tableau récapitulatif des entrées de l'API

Note sur les exemples d'utilisation

API Assiduites

assiduite

assiduite_create

assiduite_delete

assiduite_edit

assiduite_justificatifs

assiduites(-query)

assiduites_count(-query)

assiduites_create

assiduites_edit

assiduites_evaluations

assiduites_formsemestre(-query)

assiduites_formsemestre_count(-query)

assiduites_group(-query)

API Billets d'absence

billets_absence_create

billets_absence_delete

billets_absence_etudiant

API Département

departement_by_acronym

departement_create

departement_delete

departement_edit

departement_etudiants

departement_etudiants_by_id

departement_formsemestres_courants(-query)

departement_formsemestres_ids

departement_formsemestres_ids_by_id

departement_get

departements_ids

departements_list

API Étudiants

bulletin

etudiant

etudiant_annotation

etudiant_annotation_delete

etudiant_create

etudiant_edit

etudiant_formsemestres

etudiant_get_photo_image(-query)

etudiant_groups

etudiants

etudiants_by_name

etudiants_courants(-query)

API Évaluations

evaluation_assiduites

evaluation_create

evaluation_delete

evaluation_notes

evaluation_set_notes

moduleimpl_evaluations

API Formations

formation_export_by_formation_id

formation_get

formation_module_edit

formation_module_get

formation_module_set_code_apogee

formations

formations_ids

referentiel_competences

ue_assoc_niveau

ue_desassoc_niveau

ue_edit

ue_set_code_apogee

ue_set_code_apogee_rcue

ue_set_parcours

API Formsemestre

73 KiB

Raw Blame History

`assiduite`

`assiduite_create`

`assiduite_delete`

`assiduite_edit`

`assiduite_justificatifs`

`assiduites(-query)`

`assiduites_count(-query)`

`assiduites_create`

`assiduites_edit`

`assiduites_evaluations`

`assiduites_formsemestre(-query)`

`assiduites_formsemestre_count(-query)`

`assiduites_group(-query)`

`billets_absence_create`

`billets_absence_delete`

`billets_absence_etudiant`

`departement_by_acronym`

`departement_create`

`departement_delete`

`departement_edit`

`departement_etudiants`

`departement_etudiants_by_id`

`departement_formsemestres_courants(-query)`

`departement_formsemestres_ids`

`departement_formsemestres_ids_by_id`

`departement_get`

`departements_ids`

`departements_list`

`bulletin`

`etudiant`

`etudiant_annotation`

`etudiant_annotation_delete`

`etudiant_create`

`etudiant_edit`

`etudiant_formsemestres`

`etudiant_get_photo_image(-query)`

`etudiant_groups`

`etudiants`

`etudiants_by_name`

`etudiants_courants(-query)`

`evaluation_assiduites`

`evaluation_create`

`evaluation_delete`

`evaluation_notes`

`evaluation_set_notes`

`moduleimpl_evaluations`

`formation_export_by_formation_id`

`formation_get`

`formation_module_edit`

`formation_module_get`

`formation_module_set_code_apogee`

`formations`

`formations_ids`

`referentiel_competences`

`ue_assoc_niveau`

`ue_desassoc_niveau`

`ue_edit`

`ue_set_code_apogee`

`ue_set_code_apogee_rcue`

`ue_set_parcours`

`bulletins`

`formsemestre_edit`

`formsemestre_edt(-query)`

`formsemestre_etat_evaluations`

`formsemestre_etudiants(-query)`

`formsemestre_get`

`formsemestre_programme`

`formsemestre_resultat(-query)`

`formsemestre_set_apo_etapes`

`formsemestre_set_elt_annee_apo`

`formsemestre_set_elt_passage_apo`

`formsemestre_set_elt_sem_apo`

`formsemestres_query(-query)`

`groups_get_auto_assignment`

`groups_save_auto_assignment`

`formsemestre_partitions`

`formsemestre_set_partitions_order`

`group_create`

`group_delete`