forked from ScoDoc/DocScoDoc
1122 lines
58 KiB
Markdown
1122 lines
58 KiB
Markdown
|
||
## API pour ScoDoc 9
|
||
L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON.
|
||
|
||
La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification.
|
||
**Les clients de l'ancienne API ScoDoc 7 doivent être adaptés pour fonctionner avec ScoDoc 9.**
|
||
|
||
Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès en
|
||
écrivant à la liste de diffusion, ou sur le canal `#API` du Discord développeurs.
|
||
|
||
L'API fournit des données JSON, sauf exception (bulletins PDF par exemple).
|
||
|
||
Les objets ScoDoc manipulables sont identifiés par des id numériques.
|
||
|
||
* etudid: étudiant
|
||
* formation_id: un programme de formation (page "programmes");
|
||
* ue_id: une UE dans un programme;
|
||
* matiere_id: une matière dans un programme;
|
||
* module_id: un module dans un programme;
|
||
* moduleimpl_id: un module réalisé dans un semestre;
|
||
* formsemestre_id: un "semestre" de formation.
|
||
|
||
(pour plus de précisions, voir la [doc interne](Internals.md))
|
||
|
||
|
||
L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`.
|
||
|
||
## Configuration de ScoDoc pour utiliser l'API
|
||
|
||
Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.
|
||
|
||
En général, il est recommandé de créer un rôle, de lui attribuer les permissions
|
||
que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle.
|
||
|
||
En ligne de commande, cela peut se faire comme suit (voir détail des commandes
|
||
[sur le guide de configuration](GuideConfig.md)).
|
||
|
||
```
|
||
# se connecter comme utilisateur scodoc
|
||
su - scodoc
|
||
|
||
# Créer un rôle
|
||
flask create-role LecteurAPI
|
||
# Lui donner les droits nécessaires: ici 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](TestsScoDoc.md#tests-de-lapi-scodoc9).
|
||
|
||
## Essais avec HTTPie
|
||
|
||
[HTTPie](https://httpie.io/) est un client universel livre et gratuit très commode, disponible
|
||
pour Windows, Linux, en ligne de commande ou interface graphique.
|
||
|
||
Exemple d'utilisation en ligne de commande et interroger votre ScoDoc pour obtenir la
|
||
liste des départements:
|
||
```
|
||
http -a USER:PASSWORD POST 'http://localhost:5000/ScoDoc/api/tokens'
|
||
```
|
||
Qui affiche:
|
||
```
|
||
HTTP/1.1 200 OK
|
||
Content-Length: 50
|
||
Content-Type: application/json
|
||
Date: Thu, 05 May 2022 04:29:33 GMT
|
||
|
||
{
|
||
"token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
|
||
}
|
||
```
|
||
(remplacer USER:PASSWORD par les identifiants de votre utilisateur et adapter
|
||
l'URL qui est ici celle d'un client local sur le serveur de test).
|
||
|
||
Avec ce jeton (*token*), on peut interroger le serveur:
|
||
```
|
||
http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
|
||
```
|
||
qui affiche par exemple:
|
||
```
|
||
HTTP/1.1 200 OK
|
||
Content-Length: 151
|
||
Content-Type: application/json
|
||
Date: Thu, 05 May 2022 05:21:33 GMT
|
||
|
||
[
|
||
{
|
||
"acronym": "TAPI",
|
||
"date_creation": "Wed, 04 May 2022 21:09:25 GMT",
|
||
"description": null,
|
||
"id": 1,
|
||
"visible": true
|
||
}
|
||
]
|
||
```
|
||
|
||
## Fonctions d'API ScoDoc 9
|
||
|
||
La documentation ci-dessous concerne la nouvelle API, disponible à partir de la
|
||
version de ScoDoc 9.3.25.
|
||
|
||
### Accès à l'API REST
|
||
|
||
L'API est accessible à l'adresse: `https://scodoc.monsite.tld/ScoDoc/api/fonction`
|
||
(et aussi `https://scodoc.monsite.tld/ScoDoc/api/<dept_acronyme>/fonction` pour un
|
||
accès avec des droits restreints au département indiqué).
|
||
|
||
#### Authentification
|
||
|
||
Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il
|
||
vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant
|
||
d'utiliser l'api suivant les droits correspondant à votre session.
|
||
|
||
Pour obtenir le jeton, il faut un compte sur ScoDoc (`user_name`et `password`).
|
||
Les autorisations et rôles sont gérés exactement comme pour l'application.
|
||
|
||
Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des
|
||
systèmes, 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:
|
||
```json
|
||
{
|
||
"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](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK.
|
||
* [401](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Authentification nécessaire. (jeton non précisé ou invalide)
|
||
* [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403) : Action
|
||
non autorisée pour l'utilisateur associé au jeton.
|
||
* [404](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Adresse
|
||
incorrecte, paramètre manquant ou invalide, ou objet inexistant.
|
||
* [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur
|
||
inconnue côté serveur.
|
||
|
||
## Règles générales
|
||
|
||
* une route s'écrit comme une suite de noms et d'identifiants;
|
||
* les noms token, departement, formation, formsemestre, groupe, etudiant,
|
||
bulletin, absence, logo, programme, évaluation, resultat, decision désignent
|
||
des types d'objets;
|
||
* les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query,
|
||
create, delete, edit, order sont des actions;
|
||
* les noms restants (ids, courants, long, ...) sont des options, les autres noms
|
||
sont des options ou des actions;
|
||
* le dernier nom apparaissant sur une route donne le type d'objet renvoyé. Ce
|
||
nom peut apparaître au singulier ou au pluriel.
|
||
* au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404;
|
||
* au pluriel une collection d'objets est renvoyée, si aucun objet n'est
|
||
trouvé, retourne une collection vide.
|
||
* un type d'objet au singulier est généralement suivi immédiatement de son
|
||
identifiant (unique). Exception: pour un étudiant, on peut également utiliser
|
||
le NIP ou l'INE (qui ne sont pas uniques dans la base car un étudiant de même
|
||
INE/NIP peut passer par plusieurs départements).
|
||
|
||
## Référence
|
||
|
||
La [carte syntaxique](#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](#tableau-recapitulatif-des-entrees-de-lapi) vous
|
||
permet de rechercher une entrée à partir du résultat attendu.
|
||
|
||
### Carte syntaxique
|
||
|
||
|
||
|
||
### Tableau récapitulatif des entrées de l'API
|
||
|
||
Ce tableau est trié selon le type des informations renvoyées:
|
||
|
||
* un nom simple représente un seul objet de ce type;
|
||
* suivi de `+`désigne une forme 'longue' d'objet de ce type;
|
||
* suivi de `*` désigne une liste de 0, 1 ou plusieurs objets du type;
|
||
* suivi de `#` désigne une liste d'entiers (les ids des objets du type);
|
||
* suivi de `:` puis d'un nom en majuscule indique une requête (POST) qui modifie
|
||
les données de ScoDoc.
|
||
|
||
| Retour | Remarque | Méthode | Navigation |
|
||
|:------------------------|:----------------------------------|---------|---------------------------------------------------------------------------|
|
||
| departement**`*`** | tous les depts | GET | [departements](#departements) |
|
||
| departement**`#`** | tous les ids des depts | GET | [departements-ids](#departements-ids) |
|
||
| departement | recherche par id | GET | [departement](#departement) |
|
||
| departement | recherche par acronyme | GET | [departement](#departement) |
|
||
| departement:CREATE | création d'un département | POST | [departement-create](#departement-create) |
|
||
| departement:EDIT | modification d'un département | POST | [departement-edit](#departement-edit) |
|
||
| departementDELETE | suppression d'un département | POST | [departement-delete](#departement-delete) |
|
||
| formation**`*`** | toutes les formations accessibles | GET | [formations](#formations) |
|
||
| formation**`#`** | ids des formations accessibles | GET | [formations-ids](#formations-ids) |
|
||
| formation | une formation | GET | [formation](#formation) |
|
||
| export | | GET | [formation-export](#formation-export) |
|
||
| export**`+`** | | GET | [formation-export_with_ids](#formation-export_with_ids) |
|
||
| referentiel_competences | | GET | [formation-referenciel_competences](#formation-referenciel_competences) |
|
||
| formsemestre**`#`** | | GET | [departement-formsemestres_ids](#departement-formsemestres_ids) |
|
||
| formsemestre**`*`** | | GET | [departement-formsemestres_courants](#departement-formsemestres_courants) |
|
||
| formsemestre**`*`** | | GET | [formsemestre-query](#formsemestre-query) |
|
||
| formsemestre**`*`** | | GET | [etudiant-formsemestres](#etudiant-formsemestres) |
|
||
| formsemestre | | GET | [formsemestre](#formsemestre) |
|
||
| moduleimpl | | GET | [moduleimpl](#moduleimpl) |
|
||
| partition**`*`** | | GET | [formsemestre-partitions](#formsemestre-partitions) |
|
||
| partition | | GET | [partition](#partition) |
|
||
| partition:CREATE | | POST | [formsemestre-partition-create](#formsemestre-partition-create) |
|
||
| partition:EDIT | | POST | [partition-edit](#partition-edit) |
|
||
| partition:ACTION | | POST | [formsemestre-partitions-order](#formsemestre-partitions-order) |
|
||
| partition:DELETE | | POST | [partition-delete](#partition-delete) |
|
||
| partition:ACTION | | POST | [partition-remove_etudiant](#partition-remove_etudiant) |
|
||
| group:CREATE | | POST | [partition-group-create](#partition-group-create) |
|
||
| group:EDIT | | POST | [group-edit](#group-edit) |
|
||
| group:ACTION | | POST | [partition-groups-order](#partition-groups-order) |
|
||
| group:DELETE | | POST | [group-delete](#group-delete) |
|
||
| group* | | POST | [etudiant-formsemestre-groups](#etudiant-formsemestre-groups) |
|
||
| group:ACTION | | GET | [group-set_etudiant](#group-set_etudiant) |
|
||
| group:ACTION | | POST | [group-remove_etudiant](#group-remove_etudiant) |
|
||
| etudiant**`*`** | recherche par etudid, nip ou i | GET | [etudiants-clé](#etudiants-clé) |
|
||
| etudiant**`*`** | les étudiants actuels | GET | [etudiants-courant](#etudiants-courant) |
|
||
| etudiant**`*`** | | GET | [departement-etudiants](#departement-etudiants) |
|
||
| etudiant**`*`** | | GET | [formsemestre-etudiants](#formsemestre-etudiants) |
|
||
| etudiant**`*`** | | GET | [formsemestre-etudiants-query](#formsemestre-etudiants-query) |
|
||
| etudiant**`*`** | | GET | [group-etudiants](#group-etudiants) |
|
||
| etudiant**`*`** | | GET | [group-etudiants-query](#group-etudiants-query) |
|
||
| etudiant | | GET | [etudiant](#etudiant) |
|
||
| bulletin**`*`** | | GET | [formsemestre-bulletin](#formsemestre-bulletin) |
|
||
| bulletin | | GET | [etudiant-formsemestre-bulletin](#etudiant-formsemestre-bulletin) |
|
||
| programme | | GET | [formsemestre-programme](#formsemestre-programme) |
|
||
| | | GET | [formsemestre-etat_evals](#formsemestre-etat_evals) |
|
||
| | | GET | [formsemestre-resultats](#formsemestre-resultats) |
|
||
| jury | | GET | [formsemestre-decisions_jury](#formsemestre-decisions_jury) |
|
||
| evaluation* | | GET | [evaluations](#evaluations) |
|
||
| note* | | GET | [evaluation-notes](#evaluation-notes) |
|
||
| logo**`*`** | | GET | [logos](#logos) |
|
||
| logo**`*`** | | GET | [departement-logos](#departement-logos) |
|
||
| image | | GET | [logo](#logo) |
|
||
| image | | GET | [departement-logo](#departement-logo) |
|
||
| user | | GET | [user](#user) |
|
||
| user**`*`** | | GET | [users-query](#users-query) |
|
||
| user:CREATE | | POST | [user-create](#user-create) |
|
||
| user:EDIT | | POST | [user-edit](#user-edit) |
|
||
| user:DELETE | | POST | [user-delete](#user-delete) |
|
||
| user:ACTION | | POST | [user-role-add](#user-role-add) |
|
||
| user:ACTION | | POST | [user-role-remove](#user-role-remove) |
|
||
| permission**`*`** | | GET | [permissions](#permissions) |
|
||
| role**`*`** | | GET | [roles](#roles) |
|
||
| role**`*`** | | GET | [role](#role) |
|
||
| role:ACTION | | POST | [role-add_permission](#role-add_permission) |
|
||
| role:ACTION | | POST | [role-remove_permission](#role-remove_permission) |
|
||
| role:CREATE | | POST | [role-create](#role-create) |
|
||
| role:EDIT | | POST | [role-edit](#role-edit) |
|
||
| role:DELETE | | POST | [role-delete](#role-delete) |
|
||
|
||
### **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](samples/sample_departements.json.md)
|
||
|
||
#### **departements-ids**
|
||
* **Méthode:** GET
|
||
* **Routes:** `/departements_ids`
|
||
* **Résultat:** Liste des id départements (visibles ou non).
|
||
* **Exemple de résultat:**
|
||
* **Exemple de résultat:** [departements-ids.json](samples/sample_departements-ids.json.md)
|
||
|
||
#### **departement**
|
||
* **Méthode:** GET
|
||
* **Routes:**
|
||
* `/departement/id/<int:dept_id>`
|
||
* `/departement/<string:dept>`
|
||
* **Résultat:** Un département
|
||
* **Exemple de résultat:** [departement.json](samples/sample_departement.json.md)
|
||
|
||
#### **`departement-create`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Paramètres:** aucun
|
||
* **Data:** `{ "acronym": str, "visible":bool }`
|
||
* **Routes:** `/departement/create`
|
||
* **Exemple d'utilisation:** `/departement/create`
|
||
>`{ "acronym": "QLIO", "visible": true }`
|
||
* **Résultat:** Crée un nouveau département. L'acronyme du département (RT,
|
||
GEII, ...) doit être unique (il est d'usage de le mettre en majuscules, mais
|
||
ce n'est pas obligatoire). Le paramètre optionnel `visible`indique si le
|
||
département est affiché sur la page d'accueil de ScoDoc. Notez qu'un
|
||
département "invisible" peut quand même être utilisé si l'on connait son
|
||
adresse (URL). Renvoie le département créé.
|
||
* **Exemple de résultat:** [departements-create.json](samples/sample_departement-create.json.md)
|
||
|
||
#### **`departement-edit`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Paramètres:** `dept_acronym`
|
||
* **Data:** `{ "visible":bool }`
|
||
* **Routes:** `/departement/<string:dept_acronym>/edit`
|
||
* **Exemple d'utilisation:** `/departement/edit`
|
||
>`{ "visible": false }`
|
||
* **Résultat:** Modifie un département. Seul le champs `visible` peut être
|
||
modifié. L'acronyme ne peut pas être changé car il peut être mentionné dans de
|
||
nombreux objets et documents, y compris à l'extérieur de ScoDoc.
|
||
* **Exemple de résultat:** [departements-edit.json](samples/sample_departement-edit.json.md)
|
||
|
||
#### **`departement-delete`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Paramètres:** `dept_acronym`
|
||
* **Routes:** `/departement/<string:dept_acronym>/delete`
|
||
* **Exemple d'utilisation:** `/departement/delete/EARTH`
|
||
* **Résultat:** supprime définitivement un département. *Toutes les données sont effacées*
|
||
(étudiants, formations, ...).
|
||
* **Exemple de résultat:** [departements-delete.json](samples/sample_departement-delete.json.md)
|
||
|
||
### **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`** (supprimé)
|
||
* **Méthode:** GET
|
||
* **Routes:** `/etudiants
|
||
* **Exemple d'utilisation:** `/api/etudiants`
|
||
* **Résultat:** Liste complète de tous les étudiants (passés ou présents) pour
|
||
lequel l'utilisateur a la permission ScoView.
|
||
* **Exemple de résultat:** [etudiants.json] (samples/sample_etudiants.json.md)
|
||
|
||
#### **`etudiants-courants`**
|
||
* **Méthode:** GET
|
||
* **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](samples/sample_etudiants-courants.json.md)
|
||
|
||
#### **`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`](ScoDoc9API.md#etudiant) mais renvoie toujours une liste.
|
||
Si non trouvé, liste vide, pas d'erreur.
|
||
Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a
|
||
été inscrit dans plusieurs départements, on a plusieurs objets (1 par
|
||
dept.).
|
||
* **Exemple de résultat:** [etudiants-clef.json](samples/sample_etudiants-clef.json.md)
|
||
|
||
#### **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:** [departement-etudiants.json](samples/sample_departement-etudiants.json.md)
|
||
|
||
#### **`formsemestre-etudiants[-query]`**
|
||
* **Méthode:** GET
|
||
* **Paramètres:** `formsemestre_id`
|
||
* **Query string:** `etat` ('I', 'D' ou 'DEF')
|
||
* **Routes:**
|
||
* `/formsemestre/<int:formsemestre_id>/etudiants`
|
||
* `/formsemestre/<int:formsemestre_id>/etudiants/query?etat=I,D,DEF`
|
||
* **Exemple d'utilisation:**
|
||
* `/api/formsemestre/1/etudiants`
|
||
* `/api/formsemestre/1/etudiants/query?etat=D`
|
||
* **Résultat:** Etudiants d'un formsemestre spécifié par son id. Liste
|
||
restreinte aux étudiants inscrits (I), démissionnaires (D) ou défaillants
|
||
(DEF) si l'état est indiqué.
|
||
* **Exemple de résultat:**
|
||
* [formsemestre-etudiants.json](samples/sample_formsemestre-etudiants.json.md)
|
||
* [formsemestre-etudiants-query.json](samples/sample_formsemestre-etudiants-query.json.md)
|
||
|
||
#### **`group-etudiants[-query]`**
|
||
* **Méthode: GET**
|
||
* **Paramètres:** `group_id`
|
||
* **Query string:** `etat` ('I', 'D' ou 'DEF')
|
||
* **Routes:**
|
||
* `/group/<int:group_id>/etudiants`
|
||
* `/group/<int:group_id>/etudiants/query`
|
||
* **Exemple d'utilisation:**
|
||
* `/ScoDoc/api/group/1/etudiants`
|
||
* `/ScoDoc/api/group/1/etudiants/query?etat=I`
|
||
* **Résultat:** Etudiants d'un groupe spécifié par son id. Liste
|
||
restreinte aux étudiants inscrits (I), démissionnaires (D) ou défaillants
|
||
(DEF) si l'état est indiqué.
|
||
* **Exemple de résultat:**
|
||
* [group-etudiants.json](samples/sample_group-etudiants.json.md)
|
||
* [group-etudiants-query.json](samples/sample_group-etudiants-query.json.md)
|
||
|
||
#### **`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 renvoie le plus récemment inscrit.
|
||
* **Exemple de résultat:** [etudiant.json](samples/sample_etudiant.json.md)
|
||
|
||
### **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](samples/sample_formations.json.md)
|
||
|
||
#### **`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:** [formations_ids.json](samples/sample_formations_ids.json.md)
|
||
|
||
#### **`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](samples/sample_formation.json.md)
|
||
|
||
### **API Formsemestre**
|
||
|
||
Les sessions de formation (qu'elles durent une année ou un mois) sont représentées par les `formsemestre`.
|
||
|
||
#### Note sur les identifiants de formsemestre
|
||
Le `session_id` peut être utilisé pour identifier de façon prévisible et
|
||
(presque) unique un formsemestre dans un établissement, ce qui est utile
|
||
notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion
|
||
d'emplois du temps ou de services d'enseignement). Cet identifiant est constitué
|
||
des informations suivantes:
|
||
|
||
* **Département** (RT, GEII, INFO...) (acronyme en majuscules)
|
||
* **Nom parcours:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
|
||
* **Modalité:** FI, FC, FA
|
||
* **"Spécialité":** S1 (ou S1D pour les semestres décalés), ou le
|
||
`code_specialite` si pas de semestres. Le code spécialité est un champ
|
||
(libre) dans la "formation" (le programme pédagogique).
|
||
* **Année:** année de début de l'année scolaire correspondante (2014 pour
|
||
une session appartenant à l'année scolaire 2014-2015, même si elle
|
||
commence en mars 2015).
|
||
|
||
|
||
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT
|
||
informatique de 2014 en formation initiale (FI).
|
||
|
||
#### Structure Formsemestre
|
||
|
||
| attribut | type | commentaire |
|
||
|:----------------------------|:------------|:-----------------------------------------------|
|
||
| _**id**_ | int | id unique |
|
||
| _**formsemestre_id**_ | int | identification unique |
|
||
| _**semestre_id**_ | int | rang du semestre 1, ... |
|
||
| _**elt_annee_apo**_ | ??? | |
|
||
| _**titre**_ | string | |
|
||
| _**titre_court**_ | string | |
|
||
| _**titre_num**_ | string | |
|
||
| _**session_id**_ | string | cf. Note sur les identifiants de formsemestre |
|
||
| _**block_moyennes**_ | bool | inhibe le calcul des moyennes |
|
||
| _**scodoc7_id**_ | int | |
|
||
| _**date_debut**_ | date | |
|
||
| _**date_fin**_ | date | |
|
||
| _**gestion_semestrielles**_ | bool | |
|
||
| _**gestion_compensation**_ | bool | |
|
||
| _**bul_bgcolor**_ | string | Couleur (CSS) de fond du bulletin |
|
||
| _**etat**_ | bool | |
|
||
| _**dept_id**_ | int | |
|
||
| _**modalite**_ | string | "FI", "FA", ... |
|
||
| _**bul_hide_xml**_ | bool | |
|
||
| _**resp_can_change_ens**_ | bool | |
|
||
| _**resp_can_edit**_ | bool | |
|
||
| _**ens_can_edit_eval**_ | bool | |
|
||
| _**elt_sem_apo**_ | string | |
|
||
| _**parcours**_ | ???? | |
|
||
| _**annee_scolaire**_ | int | |
|
||
| _**date_debut_iso**_ | string | |
|
||
| _**date_fin_iso**_ | string | |
|
||
| _**departement**_ | Département | |
|
||
| _**etape_apo**_ | string | |
|
||
| _**formation_id**_ | int | |
|
||
| _**formation**_ | Formation | |
|
||
| _**responsables**_ | int* | liste des ids des enseignants responsables |
|
||
|
||
#### **departement-formsemestres_ids**
|
||
* **Méthode:** GET
|
||
* **Paramètres:** `dept`
|
||
* **Routes:**
|
||
* `/departement/id/<int:dept_id>/formsemestres_ids`
|
||
* `/departement/<string:dept>/formsemestres_ids`
|
||
* **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_ids`
|
||
* **Résultat:** Liste des id des formsemestres (passés ou présents) d'un
|
||
département donné.
|
||
* **Exemple de résultat:** [departement-formsemestres_ids.json](samples/sample_departement-formsemestres_ids.json.md)
|
||
|
||
#### **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](samples/sample_departement-formsemestres-courants.json.md)
|
||
|
||
#### **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-query.json](samples/sample_formsemestres-query.json.md)
|
||
|
||
#### **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](samples/sample_etudiant-formsemestres.json.md)
|
||
|
||
#### **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:** [formsemestre.json](samples/sample_formsemestre.json.md)
|
||
|
||
### **API Groupe**
|
||
|
||
#### **`partition-group-create`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoEtudChangeGroups`***
|
||
* **Paramètres:** `partition_id`
|
||
* **Data:** `{ group_name : <string> }`
|
||
* **Routes:** `/partition/<int:partition_id>/create`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/create`
|
||
>`{ "group_name" : "A" }`
|
||
* **Résultat:** Crée un groupe dans une partition.
|
||
* **Exemple de résultat:** [partition-create.json](samples/sample_formsemestre-partition-create.json.md)
|
||
|
||
#### **`group-edit`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoEtudChangeGroups`***
|
||
* **Paramètres:** `group_id`
|
||
* **Data:** `{ group_name : <string> }`
|
||
* **Routes:** `/group/<int:group_id>/edit`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/group/4581/edit`
|
||
>`{ "group_name" : "nouveau" }`
|
||
* **Résultat:** Renomme un groupe.
|
||
* **Exemple de résultat:** [group-edit.json](samples/sample_group-edit.json.md)
|
||
|
||
#### **`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:** [partition-groups-order.json](samples/sample_partition-groups-order.json.md)
|
||
|
||
#### **`group-delete`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoEtudChangeGroups`***
|
||
* **Paramètres:** `group_id`
|
||
* **Routes:** `/group/<int:group_id>/delete`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/group/4581/delete`
|
||
* **Résultat:** Supprime un groupe.
|
||
* **Exemple de résultat:** [group-delete.json](samples/sample_group-delete.json.md)
|
||
|
||
#### **etudiant-formsemestre-groups**
|
||
* **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:** [etudiant-formsemestres-groups.json](samples/sample_etudiant-formsemestre-groups.json.md)
|
||
|
||
#### **`group-set_etudiant`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoEtudChangeGroups`***
|
||
* **Paramètres:** `group_id`, `etudid`
|
||
* **Routes:** `/group/<int:group_id>/set_etudiant/<int:etudid>`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/group/4085/set_etudiant/12108`
|
||
* **Résultat:** Affecte un étudiant dans un groupe.
|
||
* **Exemple de résultat:** [groupes-set_etudiant.json](samples/sample_group-set_etudiant.json.md)
|
||
|
||
#### **`group-remove_etudiant`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoEtudChangeGroups`***
|
||
* **Paramètres:** `group_id`, `etudid`
|
||
* **Routes:** `/group/<int:group_id>/remove_etudiant/<int:etudid>`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/group/4085/remove_etudiant/12108`
|
||
* **Résultat:** Retire un étudiant d'un groupe.
|
||
* **Exemple de résultat:** [groupes-remove_etudiant.json](samples/sample_group-remove_etudiant.json.md)
|
||
|
||
### **API Jury**
|
||
#### **`formsemestre-decisions_jury`**
|
||
* **Méthode:** GET
|
||
* **Paramètres:** `formsemestre_id`
|
||
* **Routes:** `/formsemestre/<int:formsemestre_id>/decisions_jury`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/jury`
|
||
* **Résultat:** Retourne le récapitulatif des décisions jury
|
||
* **Exemple de résultat:** [formsemestre-decisions_jury.json](samples/sample_formsemestre-decisions_jury.json.md)
|
||
`
|
||
|
||
### **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](#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](samples/sample_moduleimpl.json.md)
|
||
|
||
### **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](samples/sample_formsemestre-partitions.json.md)
|
||
|
||
#### **`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](samples/sample_partition.json.md)
|
||
|
||
#### **`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:** [formsemestre-partition-create.json](samples/sample_formsemestre-partition-create.json.md)
|
||
|
||
#### **`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:** [partition-edit.json](samples/sample_partition-edit.json.md)
|
||
|
||
#### **`formsemestre-partitions-order`**
|
||
* **Méthode: POST**
|
||
* **Paramètres:** `formsemestre_id`
|
||
* **Data:** `[ <int:partition_id1>, <int:partition_id2>, ... ]`
|
||
* **Routes:** `/formsemestre/<int:formsemestre_id>/partitions/order`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/944/partitions/order`
|
||
>`[ 2048, 2054 ]`
|
||
* **Résultat:** Spécifie l'ordre des partitions d'un formsemestre.
|
||
* **Exemple de résultat:** [formsemestre-partitions-order.json](samples/sample_formsemestre-partitions-order.json.md)
|
||
|
||
#### **`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-delete.json](samples/sample_partition-delete.json.md)
|
||
|
||
#### **`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:** [partition-remove_etudiant.json](samples/sample_partition-remove_etudiant.json.md)
|
||
|
||
### **API Role**
|
||
|
||
Les rôles ont un nom et sont associés à un ensemble de permissions. Un
|
||
utilisateur pourra être associé à un ou plusieurs rôles dans chaque département
|
||
(ainsi, il ou elle peut enseigner dans un département et être administrateur
|
||
d'un autre).
|
||
|
||
#### **roles**
|
||
* **Méthode:** GET
|
||
* **Routes:** `/roles`
|
||
* **Exemple d'utilisation:** `/roles`
|
||
* **Résultat:** Liste de tous les rôles.
|
||
* **Exemple de résultat:** [roles.json](samples/sample_roles.json.md)
|
||
|
||
#### **role**
|
||
* **Méthode:** GET
|
||
* **Routes:** `/role/<str:role_name>`
|
||
* **Exemple d'utilisation:** `/role/Ens`
|
||
* **Résultat:** Liste le rôle indiqué. 404 si inexistant.
|
||
* **Exemple de résultat:** [role.json](samples/sample_role.json.md)
|
||
|
||
#### **role-add_permission**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Routes:** `/role/<str:role_name>/add_permission/<str:perm_name>`
|
||
* **Exemple d'utilisation:** `/role/Ens/add_permission/ScoView`
|
||
* **Résultat:** Ajoute la permission au rôle. 404 si l'un des deux n'existe pas.
|
||
Note: la liste des permissions est donnée sur [ConfigPermissions](ConfigPermissions.md).
|
||
* **Exemple de résultat:** [role-add_permission.json](samples/sample_role-add_permission.json.md)
|
||
|
||
#### **role-remove_permission**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Routes:** `/role/<str:role_name>/remove_permission/<str:perm_name>`
|
||
* **Exemple d'utilisation:** `/role/Ens/remove_permission/ScoView`
|
||
* **Résultat:** Retire la permission au rôle. 404 si l'un des deux n'existe pas.
|
||
Si le rôle n'a pas la permission, ne fait rien.
|
||
* **Exemple de résultat:** [role-remove_permission.json](samples/sample_role-remove_permission.json.md)
|
||
|
||
#### **role-create**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Data:** `{ "permissions" : [ permission, ... ] }`
|
||
* **Routes:** `/role/create/<str:role_name>`
|
||
* **Exemple d'utilisation:** `/role/create/LaveurDecarreaux`
|
||
> `{ "permissions" : [ 'ScoView', 'ScoUsersView' ] }`
|
||
* **Résultat:** Crée un nouveau rôle, avec les permissions indiquées.
|
||
* **Exemple de résultat:** [role-create.json](samples/sample_role-create.json.md)
|
||
|
||
#### **role-delete**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Routes:** `/role/<str:role_name>/delete`
|
||
* **Exemple d'utilisation:** `/role/LaveurDeCarreaux/delete`
|
||
* **Résultat:** Supprime ce rôle.
|
||
* **Exemple de résultat:** [role-delete.json](samples/sample_role-delete.json.md)
|
||
|
||
#### **role-edit**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoSuperAdmin`**
|
||
* **Data:** `{ "permissions" : [ permission, ... ] }`
|
||
* **Routes:** `/role/edit/<str:role_name>`
|
||
* **Exemple d'utilisation:** `/role/create/LaveurDecarreaux`
|
||
> `{ "name" : "LaveurDeVitres", "permissions" : [ 'ScoView' ] }`
|
||
* **Résultat:** Modifie le rôle: son nom et/ou ses permissions.
|
||
* **Exemple de résultat:** [role-edit.json](samples/sample_role-edit.json.md)
|
||
|
||
### **API User, Permissions**
|
||
#### **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](samples/sample_user.json.md)
|
||
|
||
#### **`user-create`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoUsersAdmin`**
|
||
* **Data:**
|
||
```
|
||
{
|
||
"user_name": str,
|
||
"dept": str or null,
|
||
"nom": str,
|
||
"prenom": str,
|
||
"active":bool (default True)
|
||
}
|
||
```
|
||
* **Routes:** `/user/create`
|
||
* **Résultat:** Crée un nouvel utilisateur. `user_name`est le login, unique et
|
||
non modifiable. L'utilisateur est normalement rattaché à un département, sauf
|
||
si est "super-administrateur".
|
||
* **Exemple de résultat:** [user-create.json](samples/sample_user-create.json.md)
|
||
|
||
#### **`users-query`**
|
||
* **Méthode:** GET
|
||
* **Routes:**
|
||
* `/users/query?departement=dept_acronym&active=1&starts_with=<str:nom>`
|
||
* **Résultat:** Liste d'utilisateurs, filtrés par département, statut, début de
|
||
nom (paramètres tous optionnels). Seuls les utilisateurs que l'on a la
|
||
permission de voir sont listés.
|
||
* **Exemple de résultat:** [users-query.json](samples/sample_users-query.json.md)
|
||
|
||
|
||
#### **`user-edit`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoUsersAdmin`**
|
||
* **Data:**
|
||
```
|
||
{
|
||
"dept": str or null,
|
||
"nom": str,
|
||
"prenom": str,
|
||
"active":bool (default True)
|
||
}
|
||
```
|
||
* **Routes:** `/user/<int:uid>/edit`
|
||
* **Résultat:** Modifie l'utilisateur d'UID indiqué.
|
||
* **Exemple de résultat:** [user-edit.json](samples/sample_user-edit.json.md)
|
||
|
||
#### **`user-role-add`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoUsersAdmin`**
|
||
* **Routes:** `/user/<int:uid>/role/<str:role_name>/add[/departement/<string:dept_acronym>]`
|
||
* **Résultat:** Attribue le rôle à l'utilisateur, dans le département indiqué
|
||
(ou tous si le département n'est pas spécifié).)
|
||
* **Exemple de résultat:** [user-role-add.json](samples/sample_user-role-add.json.md)
|
||
|
||
#### **`user-role-remove`**
|
||
* **Méthode: POST**
|
||
* **Permission: `ScoUsersAdmin`**
|
||
* **Routes:** `/user/<int:uid>/role/<str:role_name>/remove[/departement/<string:dept_acronym>]`
|
||
* **Résultat:** Retire le rôle à l'utilisateur.
|
||
* **Exemple de résultat:** [user-role-remove.json](samples/sample_user-role-remove.json.md)
|
||
|
||
#### **`permissions`**
|
||
* **Méthode:** GET
|
||
* **Routes:** `/permissions`
|
||
* **Résultat:** Liste des noms des permissions. Ces permissions ne sont pas
|
||
modifiables, mais de nouvelles peuvent apparaitre lors des mises à jour du
|
||
logiciel. Voir [ConfigPermissions](ConfigPermissions.md).
|
||
* **Exemple de résultat:** [permissions.json](samples/sample_permissions.json.md)
|
||
|
||
### ** 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](samples/sample_formsemestre-bulletins.json.md)
|
||
|
||
#### **etudiant-formsemestre-bulletin**
|
||
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules
|
||
pour un formsemestre spécifié par son id.
|
||
Par défaut les valeurs numériques sont formattées en chaînes. Si format=raw, valeurs numériques
|
||
mais pas JSON compliant à cause des _NaN_.
|
||
|
||
* **Méthode:** GET
|
||
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine`
|
||
* **Routes:**
|
||
`/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]`
|
||
ou `/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]`
|
||
ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/short][/pdf]`
|
||
* **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin`
|
||
* **Résultat:** Bulletin de l'étudiant dans le formsemestre.
|
||
Deux types de variantes possibles:
|
||
* versions `long` et `short` (`long`par défaut, ajoutez `/short` pour la version plus courte).
|
||
* version `json` et `pdf` (`json` par défaut, ajoutez `/pdf` pour la version pdf)
|
||
* **Exemple de résultat:** [etudiant-formsemestre-bulletin.json](samples/sample_etudiant-formsemestre-bulletin.json.md)
|
||
|
||
#### **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](samples/sample_formsemestre-programme.json.md)
|
||
|
||
#### **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](samples/sample_formsemestre-resultats.json.md)
|
||
|
||
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules
|
||
pour un formsemestre spécifié par son id.
|
||
Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw,
|
||
valeurs numériques mais pas JSON compliant à cause des _NaN_.
|
||
|
||
* **Exemple de résultat:**
|
||
|
||
#### **`moduleimpl-evaluations`**
|
||
* **Méthode:** GET
|
||
* **Paramètres:** `moduleimpl_id`
|
||
* **Routes:** `/moduleimpl/<int:moduleimpl_id>/evaluations`
|
||
* **Exemple d'utilisation:** `/ScoDoc/api/moduleimpl/1/evaluations`
|
||
* **Résultat:** Retourne la liste des évaluations à partir de l'id d'un
|
||
moduleimpl (quel que soit leur statut).
|
||
* **Exemple de résultat:** [moduleimpl-evaluations.json](samples/sample_moduleimpl-evaluations.json.md)
|
||
|
||
#### **`evaluations-notes`**
|
||
* **Méthode**: GET
|
||
* **Paramètres**: `evaluation_id`
|
||
* **Routes:** `/evaluation/<int:evaluation_id>/notes`
|
||
* **Exemple d'utilisation:** `/evaluation/1491/notes`
|
||
* **Résultat:** Retourne la liste des notes d'une évaluation. Les valeurs sont
|
||
non normalisées (le champ `note_max` indique le barème), et peuvent contenir
|
||
des chaînes de caractères: ABS, EXC, DEM, ...
|
||
* **Exemple de résultat:** [evaluation-notes.json](samples/sample_evaluation-notes.json.md)
|
||
|
||
#### **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](samples/sample_formsemestre-etat_evals.json.md)
|
||
|
||
### **API Export, 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](samples/sample_formation-export.json.md)
|
||
|
||
#### **`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](samples/sample_formation-referentiel_competences.json.md)
|
||
|
||
### **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](ScoDocAPI.md)
|
||
|
||
Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les
|
||
fonctions suivantes sont disponibles avec le mécanisme d'authentification
|
||
basique de ScoDoc 7. Elles sont considérées comme *obsolètes* ("deprecated") et
|
||
disparaitront en juillet 2022.
|
||
|
||
Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.
|
||
|
||
- `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/ etudid>`)
|
||
- `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`)
|
||
- `Absences/XMLgetAbsEtud` (deviendra `api/absences/ etudid>`, en json)
|
||
- `Notes/evaluation_listenotes` (non existante en ScoDoc9, trop complexe)
|
||
- `Notes/formsemestre_id` (deviendra `api/formsemestre`)
|
||
- `Notes/formsemestre_bulletinetud` (deviendra `api/etud/<etudid>/bul/<formsemestre_id>`)
|
||
- `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?)
|
||
- `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/<etudid>`)
|
||
- `groups_view` (deviendra `groups`)
|
||
|
||
Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est
|
||
à dire `https://votre.site.fr/ScoDoc/<dept>/Scolarite/`, et répondent en GET et
|
||
en POST.
|
||
|
||
Note:
|
||
- `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.
|