lyanis/DocScoDoc
1
0
Fork 0
forked from ScoDoc/DocScoDoc
Code Pull Requests Activity

API: formsemestres-query

Browse Source
This commit is contained in:
Emmanuel Viennet 2022-10-29 08:34:45 +02:00
parent 6057301482
commit d2becdc962
1 changed files with 41 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
docs/ScoDoc9API.md
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. Les objets ScoDoc manipulables sont identifiés par des id numériques.
* etudid: étudiant * etudid: étudiant
* formation_id: un programme de formation (page "programmes"); * formation_id: un programme de formation (page "programmes");
* ue_id: une UE dans un programme; * ue_id: une UE dans un programme;
* matiere_id: une matière dans un programme; * matiere_id: une matière dans un programme;
* module_id: un module dans un programme; * module_id: un module dans un programme;
* moduleimpl_id: un module réalisé dans un semestre; * moduleimpl_id: un module réalisé dans un semestre;
* formsemestre_id: un "semestre" de formation. * formsemestre_id: un "semestre" de formation.
(pour plus de précisions, voir la [doc interne](Internals.md)) (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`. L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`.
## Configuration de ScoDoc pour utiliser l'API ## 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 Exemple d'utilisation en ligne de commande et interroger votre ScoDoc pour obtenir la
liste des départements: liste des départements:
```
```bash
http -a USER:PASSWORD POST 'http://localhost:5000/ScoDoc/api/tokens' http -a USER:PASSWORD POST 'http://localhost:5000/ScoDoc/api/tokens'
``` ```
Qui affiche: Qui affiche:
```
```text
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Length: 50 Content-Length: 50
Content-Type: application/json Content-Type: application/json
@ -86,15 +88,19 @@ Date: Thu, 05 May 2022 04:29:33 GMT
"token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz" "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). l'URL qui est ici celle d'un client local sur le serveur de test).
Avec ce jeton (*token*), on peut interroger le serveur: Avec ce jeton (*token*), on peut interroger le serveur:
```
```bash
http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz" http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
``` ```
qui affiche par exemple: qui affiche par exemple:
```
```text
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Length: 151 Content-Length: 151
Content-Type: application/json 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 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`): 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 curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens
``` ```
où `SERVEUR` est l'adresse (IP ou nom) de votre serveur. où `SERVEUR` est l'adresse (IP ou nom) de votre serveur.
La réponse doit ressembler à ceci: La réponse doit ressembler à ceci:
```json ```json
{ {
"token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX" "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. complet en python d'interrogation de l'API.
#### Codes HTTP #### Codes HTTP
Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en 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 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. 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 Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès
par le serveur ScoDoc. par le serveur ScoDoc.
* [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK. * [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) * [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 * [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403) : Action
non autorisée pour l'utilisateur associé au jeton. 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. 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. inconnue côté serveur.
## Règles générales ## 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 | | role:DELETE | | POST | [role-delete](#role-delete) | ScoUserAdmin |
#### Note sur les exemples d'utilisation #### 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: 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 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 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) * 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** ### **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) * **Exemple de résultat:** [etudiant.json](samples/sample_etudiant.json.md)
### **API Formation** ### **API Formation**
#### Structure Formation #### Structure Formation
| attribut | type | commentaire | | attribut | type | commentaire |
|:----------------------------|:------------|:--------------------------------------------------| |:----------------------------|:------------|:--------------------------------------------------|
| _dept_id_ | int | _redondant avec departement.id ?_ | | _dept_id_ | int | _redondant avec departement.id ?_ |
@ -624,13 +636,14 @@ informatique de 2014 en formation initiale (FI).
* **Méthode:** GET * **Méthode:** GET
* **Permission: `ScoView`** * **Permission: `ScoView`**
* **Paramètres:** aucun * **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 * **Route:** `/formsemestres/query
* **Exemple d'utilisation:** `/api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021` * **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 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 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) * **Exemple de résultat:** [formsemestres-query.json](samples/sample_formsemestres-query.json.md)
#### **etudiant-formsemestres** #### **etudiant-formsemestres**