From 86fcd9fffb7674a8bc12f7f9f65a9bb612a60003 Mon Sep 17 00:00:00 2001 From: viennet Date: Thu, 4 Aug 2022 14:13:33 +0300 Subject: [PATCH] =?UTF-8?q?typos/d=C3=A9tails?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ScoDoc9API.md | 81 ++++++++++++++++++++++------------------------ mkdocs.yml | 5 --- 2 files changed, 38 insertions(+), 48 deletions(-) diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index ae44ce7..1d14c3c 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -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//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/` * **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//formsemestres_ids` * `/departement//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//formsemestres` ou * `/etudiant/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/` * **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/` * **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//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/` * **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//remove_etudiant/` * **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//semestre//groups` ou `/etudiant/nip//semestre//groups` ou `/etudiant/ine//semestre//groups` +* **Routes:** + `/etudiant/etudid//semestre//groups` ou + `/etudiant/nip//semestre//groups` ou + `/etudiant/ine//semestre//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/` * **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** diff --git a/mkdocs.yml b/mkdocs.yml index f48f858..2ac6ed6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -71,8 +71,3 @@ markdown_extensions: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - -plugins: - - search - - inline-svg - \ No newline at end of file