API: formsemestres-query

This commit is contained in:
Emmanuel Viennet 2022-10-29 08:34:45 +02:00
parent 6057301482
commit d2becdc962

View File

@ -12,17 +12,16 @@ 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.
* 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
@ -72,11 +71,14 @@ 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:
```
```bash
http -a USER:PASSWORD POST 'http://localhost:5000/ScoDoc/api/tokens'
```
Qui affiche:
```
```text
HTTP/1.1 200 OK
Content-Length: 50
Content-Type: application/json
@ -86,15 +88,19 @@ Date: Thu, 05 May 2022 04:29:33 GMT
"token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
}
```
(remplacer USER:PASSWORD par les identifiants de votre utilisateur et adapter
(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:
```
```bash
http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
```
qui affiche par exemple:
```
```text
HTTP/1.1 200 OK
Content-Length: 151
Content-Type: application/json
@ -133,12 +139,14 @@ 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`):
```
```bash
curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens
```
`SERVEUR` est l'adresse (IP ou nom) de votre serveur.
La réponse doit ressembler à ceci:
```json
{
"token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
@ -149,6 +157,7 @@ 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.
@ -156,13 +165,13 @@ 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
* [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
* [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
* [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur
inconnue côté serveur.
## Règles générales
@ -279,11 +288,12 @@ Ce tableau est trié selon le type des informations renvoyées:
| role:DELETE | | POST | [role-delete](#role-delete) | ScoUserAdmin |
#### Note sur les exemples d'utilisation
Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-traitements non réalisés par l'API. Il n'est par exemple pas garanti que les clés des objets json sont triées:
* les clés sont triées
* les listes de plus de 2 éléments sont tronquées à 2 éléments, la fin de la liste étant représentée par la notation nn json '...'
* les dates (au format iso) sont systématiquement remplacées par une date fixe (la date de modification d'un mot de passe peut évidement être différente de sa date de création)
* 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 (la date de modification d'un mot de passe peut évidement être différente de sa date de création)
### **API Départements**
@ -493,7 +503,9 @@ Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-
* **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 ?_ |
@ -624,13 +636,14 @@ informatique de 2014 en formation initiale (FI).
* **Méthode:** GET
* **Permission: `ScoView`**
* **Paramètres:** aucun
* **Query string:** `etape_apo`, `annee_scolaire`, `dept_acronym`, `dept_id`
* **Query string:** `annee_scolaire`, `dept_acronym`, `dept_id`, `etape_apo`, `ine`, `nip`
* **Route:** `/formsemestres/query
* **Exemple d'utilisation:** `/api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021`
* **Résultat:** Description d'un formsemestre. Si plusieurs
* **Résultat:** Description de formsemestres. 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.
retournée. Si `ine`ou `nip`sont spécifiés, cherche les formsemestres dans
lesquels un étudiant de ce code est inscrit.
* **Exemple de résultat:** [formsemestres-query.json](samples/sample_formsemestres-query.json.md)
#### **etudiant-formsemestres**