forked from ScoDoc/DocScoDoc
API: formsemestres-query
This commit is contained in:
parent
6057301482
commit
d2becdc962
@ -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
|
||||
```
|
||||
|
||||
où `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,14 +165,14 @@ 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.
|
||||
* [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
|
||||
|
||||
@ -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**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user