jmplace/DocScoDoc
1
0
Fork 0
forked from ScoDoc/DocScoDoc
Code Issues Pull Requests Projects Releases Wiki Activity

typos/détails

Browse Source
This commit is contained in:
Emmanuel Viennet 2022-08-04 14:13:33 +03:00
parent 57b9f0dc4a
commit 86fcd9fffb
2 changed files with 38 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
docs/ScoDoc9API.md
View File

@ -106,16 +106,14 @@ Date: Thu, 05 May 2022 05:21:33 GMT
] ]
``` ```
## Fonctions d'API ScoDoc 9 (work in progress) ## Fonctions d'API ScoDoc 9
Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149) La documentation ci-dessous concerne la nouvelle API, disponible à partir de la
version de ScoDoc 9.3.25.
La documentation ci-dessous concerne la **future** version de ScoDoc (9.3, avec
parties expérimentales progressivement mises en production à partir de 9.2.12).
### Accès à l'API REST ### Accès à l'API REST
Elle sera 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).
@ -161,26 +159,16 @@ par le serveur ScoDoc.
* [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.
<<<<<<< HEAD
![Carte syntaxique de l'API ScoDoc](img/API_Chart.svg)
[source svg](img/API_Chart.svg)
=======
>>>>>>> b2469f2 (dept et formation ok)
## 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ésigne des types d'objets. * 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 (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query, create, delete, edit, order sont des actions
* les noms restants (ids, courant, long, ...) sont des options * les noms restants (ids, courant, long, ...) sont des options
Les autre noms sont des options ou des actions 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 * 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 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 obket n'est trouvé, retourne une collection vide * 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) * 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)
## Référence ## Référence
@ -257,7 +245,7 @@ Ce tableau est trié selon le type des informations retournées
| attribut | type | commentaire | | attribut | type | commentaire |
|:-----------------|:--------|:---------------------------------------| |:-----------------|:--------|:---------------------------------------|
| _id_ | int | identifiant unique | | _id_ | int | identifiant unique |
| _acronym_ | string | nom du dépatement (en principe unique) | | _acronym_ | string | acronyme du département (fixe et unique) |
| _descripton_ | string | | | _descripton_ | string | |
| _visible_ | bool | affiché ou non dans la page d'accueil | | _visible_ | bool | affiché ou non dans la page d'accueil |
| _date_creation_ | string | date ISO | | _date_creation_ | string | date ISO |
@ -266,7 +254,7 @@ Ce tableau est trié selon le type des informations retournées
* **Méthode:** GET * **Méthode:** GET
* **Routes:** `/departements` * **Routes:** `/departements`
* **Exemple d'utilisation:** `/api/departements` * **Exemple d'utilisation:** `/api/departements`
* **Résultat:** Liste des tous les départements (visibles ou non). * **Résultat:** Liste de tous les départements (visibles ou non).
* **Exemple de résultat:** [departements.json](samples/sample_departements.json.md) * **Exemple de résultat:** [departements.json](samples/sample_departements.json.md)
#### **departements-ids** #### **departements-ids**
@ -295,7 +283,7 @@ Ce tableau est trié selon le type des informations retournées
| _titre_ | string | _URL encoded ?_ | | _titre_ | string | _URL encoded ?_ |
| _version_ | int | | | _version_ | int | |
| _type_parcours_ | int | | | _type_parcours_ | int | |
| _referentiel_competence_id_ | int | null si pas de referentiel associé | | _referentiel_competence_id_ | int | null si pas de référentiel associé |
| _id_ | int | id unique de formation | | _id_ | int | id unique de formation |
| _titre_officiel_ | string | | | _titre_officiel_ | string | |
| _formation_code_ | string | défini la compatibilité avec d'autres formations | | _formation_code_ | string | défini la compatibilité avec d'autres formations |
@ -307,15 +295,15 @@ Ce tableau est trié selon le type des informations retournées
* **Méthode:** GET * **Méthode:** GET
* **Routes:** `/formations` * **Routes:** `/formations`
* **Exemple d'utilisation:** `/ScoDoc/api/formations` * **Exemple d'utilisation:** `/ScoDoc/api/formations`
* **Résultat:** Retourne la liste de toutes les formations (tous * **Résultat:** Liste de toutes les formations (tous départements accessibles).
départements)
* **Exemple de résultat:** [formations.json](samples/sample_formations.json.md) * **Exemple de résultat:** [formations.json](samples/sample_formations.json.md)
#### **`formations-ids`** #### **`formations-ids`**
* **Méthode:** GET * **Méthode:** GET
* **Routes:** `/formations_ids` * **Routes:** `/formations_ids`
* **Exemple d'utilisation:** `/ScoDoc/api/formations_ids` * **Exemple d'utilisation:** `/ScoDoc/api/formations_ids`
* **Résultat:** Retourne la liste des ids de toutes les formations (tous départements accessibles) * **Résultat:** Liste des ids de toutes les formations (tous départements
accessibles).
* **Exemple de résultat:** * **Exemple de résultat:**
```json ```json
[17, 99, 32] [17, 99, 32]
@ -326,7 +314,7 @@ Ce tableau est trié selon le type des informations retournées
* **Paramètres:** `formation_id` * **Paramètres:** `formation_id`
* **Routes:** `/formation/<int:formation_id>` * **Routes:** `/formation/<int:formation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formation/1` * **Exemple d'utilisation:** `/ScoDoc/api/formation/1`
* **Résultat:** Retourne la formation d'id donné * **Résultat:** Description de la formation.
* **Exemple de résultat:** [formation.json](samples/sample_formation.json.md) * **Exemple de résultat:** [formation.json](samples/sample_formation.json.md)
### **Formsemestre** ### **Formsemestre**
@ -350,7 +338,8 @@ des informations suivantes:
commence en mars 2015). commence en mars 2015).
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI) **Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT
informatique de 2014 en formation initiale (FI).
#### **departement-formsemestres_ids** #### **departement-formsemestres_ids**
* **Méthode:** GET * **Méthode:** GET
@ -359,7 +348,8 @@ des informations suivantes:
* `/departement/id/<int:dept_id>/formsemestres_ids` * `/departement/id/<int:dept_id>/formsemestres_ids`
* `/departement/<string:dept>/formsemestres_ids` * `/departement/<string:dept>/formsemestres_ids`
* **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_ids` * **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_ids`
* **Résultat:** Liste des id des formsemestres (passés ou présents) d'un département donné. * **Résultat:** Liste des id des formsemestres (passés ou présents) d'un
département donné.
* **Exemple de résultat:** * **Exemple de résultat:**
```[ 28, 99, 3 ]``` ```[ 28, 99, 3 ]```
@ -379,7 +369,10 @@ des informations suivantes:
* **Query string:** `etape_apo`, `annee_scolaire`, `dept_acronym`, `dept_id` * **Query string:** `etape_apo`, `annee_scolaire`, `dept_acronym`, `dept_id`
* **Route:** `/formsemestres/query * **Route:** `/formsemestres/query
* **Exemple d'utilisation:** `/api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021` * **Exemple d'utilisation:** `/api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021`
* **Résultat:** Données d'un formsemestre spécifié par son id. 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 * **Résultat:** Description d'un formsemestre. 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.
* **Exemple de résultat:** [formsemestres.json](samples/sample_formsemestres.json.md) * **Exemple de résultat:** [formsemestres.json](samples/sample_formsemestres.json.md)
#### **etudiant_formsemestres** #### **etudiant_formsemestres**
@ -390,7 +383,8 @@ des informations suivantes:
* `/etudiant/nip/<string:nip>/formsemestres` ou * `/etudiant/nip/<string:nip>/formsemestres` ou
* `/etudiant/ine/<string:ine>/formsemestres` * `/etudiant/ine/<string:ine>/formsemestres`
* **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres` * **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres`
* **Résultat:** Retourne la liste des semestres qu'un étudiant a suivis, triés par ordre chronologique. (json) * **Résultat:** Liste des semestres qu'un étudiant a suivi, triés
par ordre chronologique.
* **Exemple de résultat:** [etudiant-formsemestres.json](samples/sample_etudiant-formsemestres.json.md) * **Exemple de résultat:** [etudiant-formsemestres.json](samples/sample_etudiant-formsemestres.json.md)
#### **formsemestre** #### **formsemestre**
@ -398,7 +392,7 @@ des informations suivantes:
* **Paramètres:** `formsemestre_id` * **Paramètres:** `formsemestre_id`
* **Route:** `/formsemestre/<int:formsemestre_id>` * **Route:** `/formsemestre/<int:formsemestre_id>`
* **Exemple d'utilisation:** `/api/formsemestre/1` * **Exemple d'utilisation:** `/api/formsemestre/1`
* **Résultat:** Données d'un formsemestre spécifié par son id. * **Résultat:** Description du formsemestre.
* **[Exemple de résultat:](samples/sample_formsemestre.json.md)** * **[Exemple de résultat:](samples/sample_formsemestre.json.md)**
### **Moduleimpl** ### **Moduleimpl**
@ -411,7 +405,7 @@ responsable et ses enseignants).
* **Paramètres:** `moduleimpl_id` * **Paramètres:** `moduleimpl_id`
* **Routes:** `/moduleimpl/<int:moduleimpl_id>` * **Routes:** `/moduleimpl/<int:moduleimpl_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formation/moduleimpl/1` * **Exemple d'utilisation:** `/ScoDoc/api/formation/moduleimpl/1`
* **Résultat:** Retourne la liste des moduleimpl * **Résultat:** Description du moduleimpl.
* **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl.json.md) * **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl.json.md)
### **Partition** ### **Partition**
@ -425,7 +419,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Paramètres:** `formsemestre_id` * **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/partitions` * **Routes:** `/formsemestre/<int:formsemestre_id>/partitions`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/911/partitions` * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/911/partitions`
* **Résultat:** La liste de toutes les partitions d'un formsemestre. * **Résultat:** Liste de toutes les partitions d'un formsemestre.
* **Exemple de résultat:** [formsemestre-partitions.json](samples/sample_formsemestre-partitions.json.md) * **Exemple de résultat:** [formsemestre-partitions.json](samples/sample_formsemestre-partitions.json.md)
#### **`partition`** #### **`partition`**
@ -433,7 +427,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Paramètres:** `partition_id` * **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>` * **Routes:** `/partition/<int:partition_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1963` * **Exemple d'utilisation:** `/ScoDoc/api/partition/1963`
* **Résultat:** La description d'une partition (y compris la liste de ses groupes). * **Résultat:** Description d'une partition (y compris la liste de ses groupes).
* **Exemple de résultat:** [partition.json](samples/sample_partition.json.md) * **Exemple de résultat:** [partition.json](samples/sample_partition.json.md)
#### **`formsemestre-partition-create`** #### **`formsemestre-partition-create`**
@ -480,7 +474,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Paramètres:** `partition_id` * **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>/remove_etudiant/<int:etudid>` * **Routes:** `/partition/<int:partition_id>/remove_etudiant/<int:etudid>`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/remove_etudiant/12107` * **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/remove_etudiant/12107`
* **Résultat:** Reture un étudiant des groupes de la partition. * **Résultat:** Retire un étudiant des groupes de la partition.
* **[Exemple de résultat](samples/sample_partition-remove_etudiant.json.md)** * **[Exemple de résultat](samples/sample_partition-remove_etudiant.json.md)**
### **Groupe** ### **Groupe**
@ -529,7 +523,10 @@ d'un nombre quelconque de groupes d'étudiants.
#### **etudiant-formsemestre-groupes** #### **etudiant-formsemestre-groupes**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine` * **Paramètres:** `formsemestre_id`, `etudid`, `nip`, `ine`
* **Routes:** `/etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/nip/<string:nip>/semestre/<int:formsemestre_id>/groups` ou `/etudiant/ine/<string:ine>/semestre/<int:formsemestre_id>/groups` * **Routes:**
`/etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups` ou
`/etudiant/nip/<string:nip>/semestre/<int:formsemestre_id>/groups` ou
`/etudiant/ine/<string:ine>/semestre/<int:formsemestre_id>/groups`
* **Exemple d'utilisation:** `/etudiant/nip/1/semestre/1/groups` * **Exemple d'utilisation:** `/etudiant/nip/1/semestre/1/groups`
* **Résultat:** Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json) * **Résultat:** Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json)
* **Exemple de résultat:** [groupes-formsemestre-etudiant.json](samples/sample_groupes-formsemestre-etudiant.json.md) * **Exemple de résultat:** [groupes-formsemestre-etudiant.json](samples/sample_groupes-formsemestre-etudiant.json.md)
@ -557,7 +554,8 @@ d'un nombre quelconque de groupes d'étudiants.
* **Méthode:** GET * **Méthode:** GET
* **Routes:** `/etudiants * **Routes:** `/etudiants
* **Exemple d'utilisation:** `/api/etudiants` * **Exemple d'utilisation:** `/api/etudiants`
* **Résultat:** Liste complète de tous les étudiants (passés ou présents) pour lequel l'utilisateur a la permission ScoView. * **Résultat:** Liste complète de tous les étudiants (passés ou présents) pour
lequel l'utilisateur a la permission ScoView.
* **Exemple de résultat:** [tous-les-etudiant.json](samples/sample_tous-les-etudiants.json.md) * **Exemple de résultat:** [tous-les-etudiant.json](samples/sample_tous-les-etudiants.json.md)
#### **`etudiants-clef`** #### **`etudiants-clef`**
@ -681,8 +679,6 @@ d'un nombre quelconque de groupes d'étudiants.
* **Exemple d'utilisation:** `api/formation/1/referentiel_competences` * **Exemple d'utilisation:** `api/formation/1/referentiel_competences`
* **Résultat:** Le référentiel de compétences d'une formation donnée (json). (_pas toujours présent_) * **Résultat:** Le référentiel de compétences d'une formation donnée (json). (_pas toujours présent_)
* **Exemple de résultat:** [formation-referentiel_competences.json](samples/sample_formation-referentiel_competences.json.md) * **Exemple de résultat:** [formation-referentiel_competences.json](samples/sample_formation-referentiel_competences.json.md)
*
XXX obtenir la liste des référentiels ?
### **Bulletin, Evaluations, Notes** ### **Bulletin, Evaluations, Notes**
#### **formsemestre-bulletins** #### **formsemestre-bulletins**
@ -728,15 +724,15 @@ bulletin PDF.
#### **formsemestre-resultats** #### **formsemestre-resultats**
* **Méthode:** GET * **Méthode:** GET
* **Paramètres:** `formsemestre_id` * **Paramètres:** `formsemestre_id`
* **Query string: `format` * **Query string**: `format`
* **Route:** `/formsemestres/resultats` * **Route:** `/formsemestres/resultats`
* **Exemple d'utilisation:** `/api/formsemestre/1/resultats` * **Exemple d'utilisation:** `/api/formsemestre/1/resultats`
* **Résultat:** [formsemestre-resultats.json](samples/sample_formsemestre-resultats.json.md) * **Résultat:** [formsemestre-resultats.json](samples/sample_formsemestre-resultats.json.md)
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules
pour un formsemestre spécifié par son id. pour un formsemestre spécifié par son id.
Par défaut les valeurs numériques sont formattées en chaînes. Si format=raw, valeurs numériques Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw,
mais pas JSON compliant à cause des _NaN_. valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:** * **Exemple de résultat:**
@ -755,8 +751,7 @@ mais pas JSON compliant à cause des _NaN_.
* **Routes:** `/evaluations/eval_notes/<int:evaluation_id>` * **Routes:** `/evaluations/eval_notes/<int:evaluation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/notes/1` * **Exemple d'utilisation:** `/ScoDoc/api/evaluations/notes/1`
* **Résultat:** Retourne la liste des notes d'une évaluation * **Résultat:** Retourne la liste des notes d'une évaluation
* **Exemple de résultat:** * **Exemple de résultat:** TODO XXX
XXX à revoir (à spécifier/reprendre implémentation XXX was eval_notes)
### **User** ### **User**

5
mkdocs.yml
View File

@ -71,8 +71,3 @@ markdown_extensions:
- name: mermaid - name: mermaid
class: mermaid class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format format: !!python/name:pymdownx.superfences.fence_code_format
plugins:
- search
- inline-svg