ScoDoc/DocScoDoc
7
2
Fork 10
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Emmanuel Viennet 2022-08-10 07:55:33 +02:00
parent 9c6c04c936
commit ae1dc39c84
1 changed files with 42 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/ScoDoc9API.md
View File

@ -113,9 +113,9 @@ version de ScoDoc 9.3.25.
### Accès à l'API REST ### Accès à l'API REST
L'API est accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction 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 (et aussi `https://scodoc.monsite.tld/ScoDoc/api/<dept_acronyme>/fonction` pour un
accès avec des droits restreints au département). accès avec des droits restreints au département indiqué).
#### Authentification #### 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. 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 ême chose avec la commande `http`): 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 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:
@ -155,27 +156,37 @@ par le serveur ScoDoc.
* [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 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
* une route s'écrit comme une suite de noms et d'identifiants * 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 token, departement, formation, formsemestre, groupe, etudiant,
* les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query, create, delete, edit, order sont des actions bulletin, absence, logo, programme, évaluation, resultat, decision désignent
* les noms restants (ids, courants, long, ...) sont des options des types d'objets;
Les autre noms sont des options ou des actions * les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query,
* le dernier nom apparaissant sur une route donne le type d'objet renvoyé. ce nom peut apparaître au singulier ou au pluriel create, delete, edit, order sont des actions;
* Au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404 * les noms restants (ids, courants, long, ...) sont des options, les autres noms
* Au pluriel une collection d'objets est renvoyée, si aucun objet n'est trouvé, retourne une collection vide sont des options ou des actions;
* 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) * 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 ## 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 ### 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 ### 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; * 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 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 de 0, 1 ou plusieurs objets du type;
* suivi de `#` désigne une liste d'entiers (les ids des 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 `:` puis d'un nom en majuscule indique une requête (POST) qui modifie
les données de ScoDoc.
| Retour | Remarque | Méthode | Navigation | | Retour | Remarque | Méthode | Navigation |
|:------------------------|:----------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------| |:------------------------|:----------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------|
@ -371,21 +383,14 @@ Ce tableau est trié selon le type des informations retournées
#### **formsemestre-etudiants** #### **formsemestre-etudiants**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id` * **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/etudiants` XXX voir si * **Routes:** `/formsemestre/<int:formsemestre_id>/etudiants`
filtrage par état (dem, def, ...) * **Route:** `/formsemestre/<int:formsemestre_id>/etudiants/query?etat=I,D,DEF`
* **Route:**
* `/formsemestres/etudiants`
* `/formsemestres/etudiants/demissionnaires`
* `/formsemestres/etudiants/defaillants`
* **Exemple d'utilisation:** `/api/formsemestre/1/etudiants` * **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) * **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`** #### **`group-etudiants`**
* **Méthode: GET** * **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 à * **Résultat:** Retourne les informations sur l'étudiant correspondant à
l'id passé en paramètres. l'id passé en paramètres.
Les codes INE et NIP sont uniques au sein d'un département. 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) * **Exemple de résultat:** [etudiant.json](samples/sample_etudiant.json.md)
### **API Formation** ### **API Formation**
@ -498,7 +503,7 @@ informatique de 2014 en formation initiale (FI).
| _**titre_court**_ | string | | | _**titre_court**_ | string | |
| _**titre_num**_ | string | | | _**titre_num**_ | string | |
| _**session_id**_ | string | cf. Note sur les identifiants de formsemestre | | _**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 | | | _**scodoc7_id**_ | int | |
| _**date_debut**_ | date | | | _**date_debut**_ | date | |
| _**date_fin**_ | date | | | _**date_fin**_ | date | |