From ae1dc39c8422e7efd0a1d29705a79c36a1c6dfeb Mon Sep 17 00:00:00 2001 From: viennet Date: Wed, 10 Aug 2022 07:55:33 +0200 Subject: [PATCH] Doc API: typos, changement route /formsemestre/etudiant. --- docs/ScoDoc9API.md | 79 ++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 37 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 1056ac9..7f1b8ce 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -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//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//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//etudiants` XXX voir si - filtrage par état (dem, def, ...) -* **Route:** - * `/formsemestres/etudiants` - * `/formsemestres/etudiants/demissionnaires` - * `/formsemestres/etudiants/defaillants` +* **Routes:** `/formsemestre//etudiants` +* **Route:** `/formsemestre//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 | |