Doc API: typos, changement route /formsemestre/etudiant.

This commit is contained in:
Emmanuel Viennet 2022-08-10 07:55:33 +02:00
parent 80cc8e6ca8
commit d95f7c9fdb

View File

@ -113,9 +113,9 @@ 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).
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
@ -127,9 +127,10 @@ 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 ême chose avec la commande `http`):
curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens
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
```
`SERVEUR` est l'adresse (IP ou nom) de votre serveur.
La réponse doit ressembler à ceci:
@ -155,27 +156,37 @@ par le serveur ScoDoc.
* [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 objet inexistant.
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 autre 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)
* 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)
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
Le [tableau récapitulatif](#tableau-recapitulatif-des-entrees-de-lapi) vous
permet de rechercher une entrée à partir du résultat attendu.
### Carte syntaxique
@ -183,13 +194,14 @@ Le [tableau récapitulatif](#tableau-recapitulatif-des-entrees-de-lapi) vous per
### Tableau récapitulatif des entrées de l'API
Ce tableau est trié selon le type des informations retournées
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
* 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
* 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 |
|:------------------------|:----------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------|
@ -371,21 +383,14 @@ Ce tableau est trié selon le type des informations retournées
#### **formsemestre-etudiants**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/etudiants` XXX voir si
filtrage par état (dem, def, ...)
* **Route:**
* `/formsemestres/etudiants`
* `/formsemestres/etudiants/demissionnaires`
* `/formsemestres/etudiants/defaillants`
* **Routes:** `/formsemestre/<int:formsemestre_id>/etudiants`
* **Route:** `/formsemestre/<int:formsemestre_id>/etudiants/query?etat=I,D,DEF`
* **Exemple d'utilisation:** `/api/formsemestre/1/etudiants`
* **Résultat:** Etudiants d'un formsemestre spécifié par son id. Liste est restreinte aux étudiants démissionnaires/défaillants si l'option correspondante est ajoutée au chemin
* **Résultat:** Etudiants d'un formsemestre spécifié par son id. Liste est
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-etat**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etat` (par défaut égal à "I" pour les étudiants inscrits)
* **Résultat:** les étudiants inscrits à ce semestres XXX préciser état
(DEM, DEF))
#### **`group-etudiants`**
* **Méthode: GET**
@ -415,7 +420,7 @@ Ce tableau est trié selon le type des informations retournées
* **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 ramène le plus récemment inscrit.
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**
@ -498,7 +503,7 @@ informatique de 2014 en formation initiale (FI).
| _**titre_court**_ | string | |
| _**titre_num**_ | string | |
| _**session_id**_ | string | cf. Note sur les identifiants de formsemestre |
| _**block_moyennes**_ | bool | inhibe le calcul des mmoyennes |
| _**block_moyennes**_ | bool | inhibe le calcul des moyennes |
| _**scodoc7_id**_ | int | |
| _**date_debut**_ | date | |
| _**date_fin**_ | date | |