Doc API: typos, changement route /formsemestre/etudiant.
This commit is contained in:
parent
80cc8e6ca8
commit
d95f7c9fdb
@ -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
|
||||
```
|
||||
|
||||
où `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 | |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user