ScoDoc
/
DocScoDoc
5
2
Fork 10
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

typos/détails

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 **future** version de ScoDoc (9.3, avec
parties expérimentales progressivement mises en production à partir de 9.2.12).
La documentation ci-dessous concerne la nouvelle API, disponible à partir de la
version de ScoDoc 9.3.25.
### 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
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
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
* 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 restants (ids, courant, 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 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)
## Référence
@ -257,7 +245,7 @@ Ce tableau est trié selon le type des informations retournées
| attribut | type | commentaire |
|:-----------------|:--------|:---------------------------------------|
| _id_ | int | identifiant unique |
| _acronym_ | string | nom du dépatement (en principe unique) |
| _acronym_ | string | acronyme du département (fixe et unique) |
| _descripton_ | string | |
| _visible_ | bool | affiché ou non dans la page d'accueil |
| _date_creation_ | string | date ISO |
@ -266,7 +254,7 @@ Ce tableau est trié selon le type des informations retournées
* **Méthode:** GET
* **Routes:** `/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)
#### **departements-ids**
@ -295,7 +283,7 @@ Ce tableau est trié selon le type des informations retournées
| _titre_ | string | _URL encoded ?_ |
| _version_ | 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 |
| _titre_officiel_ | string | |
| _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
* **Routes:** `/formations`
* **Exemple d'utilisation:** `/ScoDoc/api/formations`
* **Résultat:** Retourne la liste de toutes les formations (tous
départements)
* **Résultat:** Liste de toutes les formations (tous départements accessibles).
* **Exemple de résultat:** [formations.json](samples/sample_formations.json.md)
#### **`formations-ids`**
* **Méthode:** GET
* **Routes:** `/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:**
```json
[17, 99, 32]
@ -326,7 +314,7 @@ Ce tableau est trié selon le type des informations retournées
* **Paramètres:** `formation_id`
* **Routes:** `/formation/<int:formation_id>`
* **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)
### **Formsemestre**
@ -350,7 +338,8 @@ des informations suivantes:
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**
* **Méthode:** GET
@ -359,7 +348,8 @@ des informations suivantes:
* `/departement/id/<int:dept_id>/formsemestres_ids`
* `/departement/<string:dept>/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:**
```[ 28, 99, 3 ]```
@ -379,7 +369,10 @@ des informations suivantes:
* **Query string:** `etape_apo`, `annee_scolaire`, `dept_acronym`, `dept_id`
* **Route:** `/formsemestres/query
* **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)
#### **etudiant_formsemestres**
@ -390,7 +383,8 @@ des informations suivantes:
* `/etudiant/nip/<string:nip>/formsemestres` ou
* `/etudiant/ine/<string:ine>/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)
#### **formsemestre**
@ -398,7 +392,7 @@ des informations suivantes:
* **Paramètres:** `formsemestre_id`
* **Route:** `/formsemestre/<int:formsemestre_id>`
* **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)**
### **Moduleimpl**
@ -411,7 +405,7 @@ responsable et ses enseignants).
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/moduleimpl/<int:moduleimpl_id>`
* **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)
### **Partition**
@ -425,7 +419,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/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)
#### **`partition`**
@ -433,7 +427,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>`
* **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)
#### **`formsemestre-partition-create`**
@ -480,7 +474,7 @@ d'un nombre quelconque de groupes d'étudiants.
* **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>/remove_etudiant/<int:etudid>`
* **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)**
### **Groupe**
@ -529,7 +523,10 @@ d'un nombre quelconque de groupes d'étudiants.
#### **etudiant-formsemestre-groupes**
* **Méthode:** GET
* **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`
* **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)
@ -557,7 +554,8 @@ d'un nombre quelconque de groupes d'étudiants.
* **Méthode:** GET
* **Routes:** `/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)
#### **`etudiants-clef`**
@ -681,8 +679,6 @@ d'un nombre quelconque de groupes d'étudiants.
* **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_)
* **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**
#### **formsemestre-bulletins**
@ -728,15 +724,15 @@ bulletin PDF.
#### **formsemestre-resultats**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Query string: `format`
* **Query string**: `format`
* **Route:** `/formsemestres/resultats`
* **Exemple d'utilisation:** `/api/formsemestre/1/resultats`
* **Résultat:** [formsemestre-resultats.json](samples/sample_formsemestre-resultats.json.md)
Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules
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
mais pas JSON compliant à cause des _NaN_.
Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw,
valeurs numériques mais pas JSON compliant à cause des _NaN_.
* **Exemple de résultat:**
@ -755,8 +751,7 @@ mais pas JSON compliant à cause des _NaN_.
* **Routes:** `/evaluations/eval_notes/<int:evaluation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/evaluations/notes/1`
* **Résultat:** Retourne la liste des notes d'une évaluation
* **Exemple de résultat:**
XXX à revoir (à spécifier/reprendre implémentation XXX was eval_notes)
* **Exemple de résultat:** TODO XXX
### **User**

5
mkdocs.yml
View File

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