diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 0c8d235..6bfb677 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -12,17 +12,16 @@ L'API fournit des données JSON, sauf exception (bulletins PDF par exemple). Les objets ScoDoc manipulables sont identifiés par des id numériques. - * etudid: étudiant - * formation_id: un programme de formation (page "programmes"); - * ue_id: une UE dans un programme; - * matiere_id: une matière dans un programme; - * module_id: un module dans un programme; - * moduleimpl_id: un module réalisé dans un semestre; - * formsemestre_id: un "semestre" de formation. +* etudid: étudiant +* formation_id: un programme de formation (page "programmes"); +* ue_id: une UE dans un programme; +* matiere_id: une matière dans un programme; +* module_id: un module dans un programme; +* moduleimpl_id: un module réalisé dans un semestre; +* formsemestre_id: un "semestre" de formation. (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. @@ -156,14 +165,14 @@ que la requête a été traitée avec succès. Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par le serveur ScoDoc. - * [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK. - * [401](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Authentification nécessaire. (jeton non précisé ou invalide) - * [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 invalide, ou objet inexistant. - * [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur - inconnue côté serveur. +* [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK. +* [401](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Authentification nécessaire. (jeton non précisé ou invalide) +* [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 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 @@ -186,7 +195,7 @@ par le serveur ScoDoc. 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). @@ -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 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 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) ### **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**