API: formsemestres-query

docs/ScoDoc9API.md

@@ -22,7 +22,6 @@ Les objets ScoDoc manipulables sont identifiés par des id numériques.
 
 (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`.
 
 ## 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
 liste des départements:
-```
+
+```bash
 http -a USER:PASSWORD POST  'http://localhost:5000/ScoDoc/api/tokens'
 ```
+
 Qui affiche:
-```
+
+```text
 HTTP/1.1 200 OK
 Content-Length: 50
 Content-Type: application/json
@@ -86,15 +88,19 @@ Date: Thu, 05 May 2022 04:29:33 GMT
     "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).
 
 Avec ce jeton (*token*), on peut interroger le serveur:
-```
+
+```bash
 http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
 ```
+
 qui affiche par exemple:
-```
+
+```text
 HTTP/1.1 200 OK
 Content-Length: 151
 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
 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 
 ```
 
 où `SERVEUR` est l'adresse (IP ou nom) de votre serveur.
 La réponse doit ressembler à ceci:
+
 ```json
 {
   "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.
 
 #### Codes HTTP
+
 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
 que la requête a été traitée avec succès.
@@ -279,11 +288,12 @@ Ce tableau est trié selon le type des informations renvoyées:
 | role:DELETE             |                                         | POST    | [role-delete](#role-delete)                                               | ScoUserAdmin        |
 
 #### 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:
 
 * 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**
@@ -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)
 
 ### **API Formation**
+
 #### Structure Formation
+
 | attribut                    | type        | commentaire                                       |
 |:----------------------------|:------------|:--------------------------------------------------|
 | _dept_id_                   | int         | _redondant avec departement.id ?_                 |
@@ -624,13 +636,14 @@ informatique de 2014 en formation initiale (FI).
 * **Méthode:** GET
 * **Permission: `ScoView`**
 * **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
 * **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
   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)
 
 #### **etudiant-formsemestres**