DocScoDocPE/docs/ScoDoc9API.md

#  API pour ScoDoc 9
L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON.

La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification. 
**Les clients de l'ancienne API ScoDoc 7 doivent être adaptés pour fonctionner avec ScoDoc 9.**

Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès en écrivant à la liste de diffusion.

L'API fournit des données JSON, sauf exception (bulletins).

Les objets ScoDoc manipulables sont identifiés par des id.

 * 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`.

# Fonctions de l'API ScoDoc 7 portées en ScoDoc 9

L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md)

Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les
fonctions suivantes sont disponibles avec le mécanisme d'authentification
basique de ScoDoc 7. Elles sont considérées comme *obsolètes* ("deprecated") et
disparaitront en juillet 2022.

Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.

 - `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/ etudid>`)
 - `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`)
 - `Absences/XMLgetAbsEtud` (deviendra `api/absences/ etudid>`, en json)
 - `Notes/evaluation_listenotes` (non existante en ScoDoc9, trop complexe)
 - `Notes/formsemestre_id` (deviendra `api/formsemestre`)
 - `Notes/formsemestre_bulletinetud` (deviendra `api/etud/<etudid>/bul/<formsemestre_id>`)
 - `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?)
 - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/<etudid>`)
 - `groups_view` (deviendra `groups`)

Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est
à dire `https://votre.site.fr/ScoDoc/<dept>/Scolarite/`, et répondent en GET et
en POST.

Note: 
 - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.

# Fonctions d'API ScoDoc 9 (work in progress)

Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149)

La documentation ci-dessous concerne la **future** version De ScoDoc.

## Accès à l'API REST

Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction

### Authentification

Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il
vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant
d'utiliser l'api suivant les droits correspondant à votre session.

Pour obtenir le jeton, il faut un compte sur ScoDoc (`user_name`et `password`).
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):
  
    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:
```
{
  "token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
}
```

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.

Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs.

  * [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK.
  * [400](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Paramètre manquant, ou valeur incorrecte.
  * [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. (crédits épuisés, URL non autorisée, etc) 
  * [404](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/404) : Page inaccessible. (URL inconnue / impossible d'accéder à l'adresse)
  * [406](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/406) : Le JSON indiqué en données POST n'est pas valide.
  * [408](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/408) : Dépassement du temps maximal autorisé pour l’audit.
  * [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur inconnue, contactez-nous.
  * [503](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/503) : L'API est momentanément indisponible, réessayez dans quelques minutes.


##  Départements
  * **`departements`** 
    * **Méthode:** GET
    * **Paramètres:** `viewable` (optionnel, si faux liste aussi les
      départements non accessibles à l'utilisateur courant), `format` (json,
      xml)
    * **Routes:** `/api/departements`
    * **Exemple d'utilisation:** `/api/departements`
    * **Résultat:** Liste des id de départements.
    * **Exemple de résultat:** `[id_1, id_2, id_3, ...]`

    
  * **`etudiants`** XXX à revoir
    * **Méthode:** GET
    * **Paramètres:** `dept`, `semestre`
    * **Routes:** `/api/departements/<str:dept>/etudiants/liste/<int:formsemestre_id>`
    * **Exemple d'utilisation:** `/api/departements/MMI/etudiants/liste`
    * **Résultat:** liste des étudiants d'un département - semestre actuel par
      défaut. XXX à préciser

    
  * **`liste_semestres_actifs`** XXX à revoir 
    * **Méthode:** GET
    * **Paramètres:** `dept`
    * **Routes:** `/api/departements/<str:dept>/semestres_actifs`
    * **Exemple d'utilisation:** `/api/departements/MMI/semestres_actifs`
    * **Résultat:** Liste des semestres actifs d'un département donné. (_réponse sous format json_)
    

  * **`referentiel_competences`** *XXX pourquoi le dept est dans la route ?*
    * **Méthode:** GET
    * **Paramètres:** `dept`, `formation_id` (_`formation_id` étant un id de formation, un programme pédagogique_)
    * **Routes:** `/api/departements/<str:dept>/formations/<int:formation>/referentiel_competences`
    * **Exemple d'utilisation:** `/api/departements/MMI/formations/12/referentiel_competences`
    * **Résultat:** Le référentiel de compétences d'une formation donnée. (_pas toujours présent_)

  * XXX  obtenir la liste des référentiels

##  Etudiants
  * **`etud_dept`**
    * **Méthode:** GET
    * **Paramètres:** `code_nip`
    * **Routes:** `/api/etud_dept/<int:code_nip>`
    * **Exemple d'utilisation:** `/api/etud_dept/123`
    * **Résultat:** Liste des étudiants avec le code NIP donné tirée par ordre d'inscription décroissant.
    * **Exemple de résultat:** 
      ```
      [
       {
        exist: true,
        dept: "GEII",
        id: 987,
        dept_id: 3
       }
      ]
      ```
    

  * **`etudiant`**
    * **Méthode:** GET
    * **Paramètres:**  `etudid`
    * **Routes:** `/api/etudiant/<int:etudid>`
    * **Exemple d'utilisation:** `/api/etudiant/987`
    * **Résultat:** Un dictionnaire avec les informations de l'étudiant correspondant à l'id passé en paramètres.
    * **Exemple de résultat:**
      ```
      {
        "nom": "Mutis",
        "sexe": "M.",
        "email": "alvaro.mutis@example.com",
        "prenom": "ALVARO",
        "nomprenom": "M. Alvaro MUTIS",
        "insemestre": [
                       {
                         "etat": "I",
                         "formsemestre_id": "12781",
                         "date_fin": "2010-07-30",
                         "date_debut": "2010-01-25"
                         "parcours_type": XXX type de parcours, en discussion XXX
                       },
                      {
                        "etat": "I",
                        "formsemestre_id": "8396",
                        "date_fin": "2009-01-16",
                        "date_debut": "2008-09-01"
                      }
         ],
        "etudid": "8768",
        "domicile": "2 Rue Madame",
        "villedomicile": "Paris",
        "telephonemobile": ""
       }
      ```
    

  * **`etudiant_bulletin_semestre`**
    * **Méthode:** GET
    * **Paramètres:**  `etudid`, `sem_id`
    * **Routes:** `/api/etudiant/<int:etudid>/semestre/<int:sem_id>/bulletin`
    * **Exemple d'utilisation:** `/api/etudiant/987/semestre/12/bulletin`
    * **Résultat:** Le bulletin d'un étudiant en fonction de son id et d'un semestre donné.
    * **Exemple de résultat:** voir plus bas sur cette page.
    
    Voir aussi [Bulletins par défaut](https://scodoc.org/ParametrageBulletins/#exemple-1-bulletins-par-defaut)


 * **`etudiant_bulletin`**
    * **Méthode:** GET
    * **Paramètres:** `formsemestre_id`, `dept`, `etudid`, `format` (`pdf` ou `json` _par défaut json_), `version` (`short`, `selectedevals` ou `long`)
    * **Routes:** : `/api/formsemestre/<int:formsemestre_id>/departements/<str:dept>/etudiant/nip|id|ine/{NIP}|{etudid}|numScodoc}/releve`
    * **Exemple d'utilisation:** `/api/formsemestre/123/departements/MMI/etudiant/id/456/releve?format=pdf&version=short`
    * **Résultat:** Un bulletin de notes.
    * **Exemple de résultat:** ici au format JSON, pour une version courte (`version=short`)
```
{
"rang": {
  "ninscrits": 52,
  "value": "1"
},
"etape_apo2": "",
"etape_apo3": "",
"etape_apo4": "",
"etudiant": {
  "nom": "BOLANO",
  "prenom": "Roberto",
  "sexe": "M.",
  "code_ine": "",
    etudid": "9860",
  "code_nip": "123456789",
  "email": "roberto@santateresa.mx",
  "photo_url": "\/ScoDoc\/static\/photos\/F68\/RT_29960.h90.jpg"
},
"bonus_sport_culture": {
  "value": 0
},
"absences": {
  "nbabsjust": 0,
  "nbabs": 1
},
"decision": {
  "etat": "I",
  "code": "ADM",
  "compenseformsemestre_id" : "SEM12345" /* si ce semestre en compense un autre */
},
"note": {
  "max": "15.51",
  "moy": "10.80",
  "value": "15.51",
  "min": "07.29"
},
  etudid": "9860",
"decision_ue": [
  {
    "acronyme": "UE11",
    "code": "ADM",
    "ects": "16.0",
    "titre": "D\u00e9couverte m\u00e9tiers",
    "numero": "11",
    "ue_id": "UE21456"
  },
  {
    "acronyme": "UE12",
    "code": "ADM",
    "ects": "14.0",
    "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques",
    "numero": "12",
    "ue_id": "UE21478"
  }
],
"ue_capitalisee": [
  
],
"publie": 1,
"autorisation_inscription": [
  {
    "semestre_id": 2
  }
],
"appreciation": [
  
],
"note_max": {
  "value": 20
},
"date": "2014-07-12T17:38:47.693262",
"rang_group": [
  {
    "ninscrits": 26,
    "value": "1",
    "group_type": "TD",
    "group_name": "B"
  },
  {
    "ninscrits": 13,
    "value": "1",
    "group_type": "TP",
    "group_name": "B1"
  },
  ...
  
],
formsemestre_id": "SEM12345",
"etape_apo": "V1RT",
"ue": [
  {
    "acronyme": "UE11",
    "rang": "1",
    "code_apogee": "VRTU11",
    "ects": "16",
    "numero": "11",
    "note": {
      "max": "16.17",
      "value": "16.17",
      "min": "06.56"
    },
    "module": [
      {
        "coefficient": 3,
        "rang": {
          "value": "1"
        },
        "code": "M1101",
        "code_apogee": "VRT1101",
        "numero": 1101,
        "note": {
          "moy": "08.94",
          "nb_notes": 51,
          "nb_missing": 0,
          "max": "19.18",
          "min": "03.70",
          "nb_valid_evals": 3,
          "value": "19.18"
        },
        "abbrev": "R\u00e9seaux d&apos;entreprises",
        "effectif": {
          "value": 51
        },
        "titre": "Initiation aux r\u00e9seaux d&apos;entreprises",
        "evaluation": [
        ],
        "id": "27427"
      },
      {
        "coefficient": 2,
        "rang": {
          "value": "2"
    ],
    "effectif": "51",
    "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques",
    "id": "UE21478"
  },
  ...
  
  {
    "acronyme": "UE 1S",
    "rang": "1 ex",
    "code_apogee": "",
    "ects": "0",
    "numero": "13",
    "note": {
      "max": "00.00",
      "value": "00.00",
      "min": "00.00"
    },
    "module": [
    ],
    "effectif": "51",
    "titre": "Sport &amp;amp; Culture",
    "id": "UE23716"
  }
],
"situation": "Inscrit le 2015-09-02. D\u00e9cision jury: Valid\u00e9.  UE acquises: UE11, UE12.  Autoris\u00e9 \u00e0 s&apos;inscrire en S2."
}
```



  * **`etudiant_photo`**
    * **Méthode:** GET
    * **Paramètres:**  `etudid`, `small`
    * **Routes:** `/api/etudiant/<int:etudid>/photo` **OU** `/api/etudiant/<int:etudid>/photo/small` (_ajout du paramètre **small** pour la version small_)
    * **Exemple d'utilisation:** `/api/etudiant/123/photo` **OU** `/api/etudiant/123/photo/small` (_pour la version small_)
    * **Résultat:** Image en JPEG ou PNG.


  * **`etudiant_groups`**
    * **Méthode:** GET
    * **Paramètres:**  `etudid`, `formsemestre_id`
    * **Routes:** `/api/etudiant/<int:etudid>/semestre/<int:formsemestre_id>/groups`
    * **Exemple d'utilisation:** `/api/etudiants/123/semestre/INFO-DUT-FI-S1-2014/groups`
    * **Résultat:** Liste des groupes auxquels appartient l'étudiant dans le semestre indiqué.
    
```
{
  "etudid" : 1234,
  "formsemestre_id" : 5678,
  "groupes" : [
    {
        "numero": 1,        // Ordre d'affichage dans Scodoc
        "partition_id": 62028,
        "partition_name": "TD",
        "group_id" : 1899,
        "group_name": "TD 1"
    },{
        "numero": 2,
        "partition_id": 62029,
        "partition_name": "TP",
        "group_id" : 1905,
        "group_name": "TP 2"
    }
  ]
}
```



##  Programmes de formations 
  * **`formations`**
    * **Méthode:** GET
    * **Paramètres:** `formation_id` (_optionnel, si absent, liste toutes les formations_)
    * **Routes:** `/api/formations` **ou** `/api/formations/<int:formation_id>`
    * **Exemple d'utilisation:** `/api/formations` **ou** `/api/formations/1` 
    * **Résultat:** Liste des formations.
    * **Exemple de résultat:** `[formation_1, formation_2, formation_3, ...]`
    * TODO: détailler le contenu publié



  * **`formation_export`**
    * **Méthode:** GET
    * **Paramètres:** `formation_id`, `export_ids` (_par défaut "faux"_)
    * **Routes:** `/api/formations/formation_export/<int:formation_id>`
    * **Exemple d'utilisation:** `/api/formations/formation_export/596` **ou** `/api/formations/formation_export/596?format=xml&export_ids=1`
    * **Résultat:** La formation, avec UE, matières, modules (_un arbre_).
    * **Exemple de résultat:**
```
  {
    "nom": "formation",
    "UE": "ue",
    "matieres": [
                  "matiere_1": "maths",
                  "matiere_2": "anglais",
                  ...
                  ],
    "modules": ...
  }
```
      
## UE
 * **`UEs`**
   * **Méthode:** GET
   * **Paramètres:** `dept`, `̀semestre`
   * **Routes:** `/api/departements/<str:dept>/formations/programme/<str:semestre>`
   * **Exemple d'utilisation:** `̀/api/departements/MMI/formations/programme/INFO-DUT-FI-S1-2014`
   * **Résultat:** Liste des UEs, ressources et SAE d'un semestre
    

  

##  Semestres de formation 
Les sessions de formation (dénommées "semestres" même si elles durent une année ou un mois) sont représentées par les `formsemestre`.

  * **`formsemestre`**
    * **Méthode:** GET
    * **Paramètres:** `formsemestre_id` ou `etape_apo`, `format`(json ou xml)
    * **Routes:** `/api/formations/formsemestre/<int:formsemestre_id>`, `/api/formsemestre/apo/<etape_apo>`
    * **Exemple d'utilisation:** `/api/formations/formsemestre/12`
    * **Résultat:** Informations sur le(s) formsemestre(s).
    * **Exemple de résultat:**
```
[ 
  {
  "annee_scolaire": "2022 - 2023",
  "date_debut": "2022-09-01",
  "date_fin": "2023-02-02",
  "modalite": "FI",
  "periode": 1,
  "semestre_idx_txt": "S3",
  "semestre_idx" : 3,
  "session_id" : "GEII-BUT-FI-S3-2022",
  "titre_annee": "BUT Génie Electrique et Informatique Industrielle semestre 3 FI 2021-2022"
  "titre_num": "BUT Génie Electrique et Informatique Industrielle semestre 3",
  "titre": "BUT Génie Electrique et Informatique Industrielle",
  "parcours_type": XXX type de parcours
  'formation_id": 87,
  }
]
```

### Note sur les identifiants de sessions
Le `session_id` peut être utilisé pour identifier de façon prévisible et
(presque) unique une session dans un établissement, ce qui est utile
notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois
du temps ou de services d'enseignement). Cet identifiant est constitué des
informations suivantes:

  * **Département** (RT, GEII, INFO...) (= paramètre `DeptName`, en majuscules)
  * **Nom parcours:** BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
  * **Modalité:** FI, FC, FA
  * **"Spécialité":** S1 (ou S1D pour les semestres décalés), ou le
      `code_specialite` si pas de semestres. Le code spécialité est un champ
      (libre) nouveau dans la "formation" (programme pédagogique).
    * **Année:** année de début de l'année scolaire correspondante (2014 pour
      une session appartenant à l'année scolaire 2014-2015, même si elle
      commence en mars 2015).


**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI)


##  Modules de formation
Les moduleimpl sont les modules d'un semestre, ou les ressources, ou les SAÉs.
On peut récupérer soit un module par son id, soit la listes des modules d'un semestre.
 
 * **`moduleimpl`**
    * **Méthode:** GET
    * **Paramètres**: `formsemestre_id` ou `moduleimpl_id`
    * **Routes:** `/api/formations/moduleimpl/<int:moduleimpl_id>` **ou** `/api/formations/moduleimpl/<int:moduleimpl_id>/formsemestre/<int:formsemestre_id>`
    * **Résultat:** liste de moduleimpl
    * **Exemple de résultat:** 
      TODO





##  Groupes et partitions 

L'ensemble des étudiants d'un semestre peut être réparti selon une ou
plusieurs partitions (types de groupes). Chaque partition est constituée
d'un nombre quelconque de groupes d'étudiants.

  * **`partition`**
    * **Méthode: GET**
    * **Paramètres:** `formsemestre_id`
    * **Routes:** `/api/partitions/<int:formsemestre_id>`
    * **Exemple d'utilisation:** `/api/partition/48`
    * **Résultat:** La liste de toutes les partitions d'un formsemestre.
    * **Exemple de résultat:** 
```
[
   {
      "formsemestre_id":"12781",
      "partition_id":"23840",
      "partition_name":"TD""group":[
         {
            "formsemestre_id":"12781",
            "partition_id":"23840",
            "group_name":"A",
            "group_id":"23841",
            "partition_name":"TD"
         },
         {
            "formsemestre_id":"12781",
            "partition_id":"23840",
            "group_name":"B",
            "group_id":"23843",
            "partition_name":"TD"
         }
      ]
   },
   {
      "formsemestre_id":"12781",
      "partition_id":"23941",
      "partition_name":"TP""group":[
         {
            "..."
         },
         "..."
      ]
   },
   {
      "formsemestre_id":"12781",
      "partition_id":"22833",
      "partition_name":null"group":[
         {
            "formsemestre_id":"12781",
            "partition_id":"22833",
            "group_name":null,
            "group_id":"G22834",
            "partition_name":null
         }
      ]
   }
]
```


  * **`groups`**
    * **Méthode:** GET
    * **Paramètres:** `formsemestre_id` ou `group_ids` (_peut être répété_), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I` 
    * **Routes:** `api/partitions/formsemestre/<int:formsemestre_id>/groups/group_ids?with_codes=0|1&all_groups=0|1&etat=None|I`
    * **Exemple d'utilisation:** `api/partitions/formsemestre/213/groups/123?with_codes=1`
    * **Résultat:** Liste des étudiants dans un groupe.
    * **Exemple de résultat au format XML:** (_avec `with_codes=1`_)
```
<group_list origin="" caption="soit 21 étudiants inscrits et 2 démissionaires." id="gt_711068">

    <etud>
        <nom value="TOTO"/>
        <prenom value="Marc"/>
        <etat value="I"/>
        <email value="toto@example.com"/>
        <etudid value="9876"/>
        <code_nip value="987654"/>
        <code_ine value=""/>
    </etud>

    <etud>
        <nom value="ALVIS SAMOS"/>
        <prenom value="NATHALIE"/>
        <etat value="I"/>
        <email value="xxx@example.com"/>
        <etudid value="12345"/>
        <code_nip value="12345678"/>
        <code_ine value=""/>
    </etud>
</group_list>
```

  * **Exemple de résultat au format JSON:**
```
[
  {
    "etat":"I",
    "emailperso":null,
    "prenom":"Dalil",
    "nom_disp":"CLINTO",
    "email":"xxx@example.com",
    "62029":"A",
    "62032":null,
    "62031":"G1",
    "62030":"A1"
  },
  {  
    "etat":"I",
    "emailperso":null,
    "prenom":"Georges",
    "nom_disp":"BUSH",
    "email":"bush@example.com",
    "62029":"A",
    "62032":null,
    "62031":"G1",
    "62030":"A1"
  },
  ...
]
```

  
  * **`set_groups`**
    * **Méthode:** POST
    * **Paramètres:** `partition_id`, `groups`, `groups_to_delete`, `groups_to_create`
    * **Routes:** `/api/partitions/set_groups?partition_id=<int:partition_id>&groups=<int:groups>&groups_to_delete=<int:groups_to_delete>&groups_to_create=<int:groups_to_create>`
    * **Exemple d'utilisation:** `/api/partitions/set_groups?partition_id=65&groups=77&groups_to_delete=8&groups_to_create=4`
    * **Résultat:** Set les groups.
      
    TODO: à changer, passer les paramètres dans le corps de la requête


##  Bulletins de notes 
  * **`evaluations`**
    * **Méthode:** GET
    * **Paramètres:** `moduleimpl_id`
    * **Routes:** `/api/evaluations/<int:moduleimpl_id>`
    * **Exemple d'utilisation:** `/api/evaluations/54`
    * **Résultat:** Liste des évaluations à partir de l'id d'un moduleimpl.
    * **Exemple de résultat:** `[eval_1, eval_2, eval_3, ...]`


  * **`evaluation_notes`**
    * **Méthode**: GET
    * **Paramètres**: `evaluation_id`
    * **Routes:** `/api/evaluations/eval_notes/<int:evaluation_id>`
    * **Exemple d'utilisation:** `/api/evaluations/eval_notes/24`
    * **Résultat:** Liste des notes à partir de l'id d'une évaluation donnée.
    * **Exemple de résultat:** 
```
[
  {
    "84": "13",
    "85": "15",
    "86": "9",
    ...
  }
]
```


  * **`evaluation_set_notes`**
    * **Méthode:** POST
    * **Paramètres:** `eval_id`,  `etudid`, `note`
    * **Routes:** `/api/evaluations/eval_set_notes?eval_id=<int:eval_id> etudid=<int etudid>&note=<int:note>`
    * **Exemple d'utilisation:** `/api/evaluations/eval_set_notes?eval_id=6 etudid=456&note=15`
    * **Résultat:** Set les notes d'une évaluation pour un étudiant donné.
      TODO vérifier et passer les valeurs dans le corps.
    

##  Absences
**Remarques**, les dates sont au format iso `yyyy-mm-dd`. Les dates de fin ne sont pas incluses. Et `demi_journee`= 2 si journée complète, =1 si uniquement le matin, =0 si uniquement l'après-midi.


 * **`absences`**
     * **Méthode:** GET
     * **Paramètres:**  `etudid`, `abs_just_only, format`, `abs_just_only` (_spécifie si on veut les absences justifiées ou non_).
     * **Routes:** `/api/absences/<int:etudid>`
     * **Exemple d'utilisation:** `/api/absences/54`
     * **Résultat:** Liste des absences d'un étudiant donné.
     * **Exemple de résultat:**
     ```{jour: "2021-02-10", ampm: "0", description: "M2202",  }``` (_**ampm** vaut 1 le matin et 0 l'après-midi_).

 
 * **`abs_signale`**
    * **Méthode:** POST
    * **Paramètres:** `date_debut`, `date_fin`, `module_impl_id=None`, `demi_journee=2`, `estjust=False`, `description`, `etudid`
    * **Body de la requête:** `date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&description=description&etudid=<int:etudid>`
    * **Exemple d'utilisation:** `date_debut=2015-02-01&date_fin=2015-02-03&demi_journee=4&description=""&etudid=874`
    * **Résultat:** *html*
    

 * **`abs_annule`**
    * **Méthode:** POST
    * **Paramètres:** `date_debut`, `date_fin`, `demi_journee`, `etudid`
    * **Body de la requête:** `date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee&etudid=<int:etudid>`
    * **Exemple d'utilisation:** `date_debut=2004-05-03&date_fin=2004-06-07&demi_journee=2&etudid=451`
    * **Résultat:** *html*


 * **`abs_annule_justif`**
    * **Méthode:** POST
    * **Paramètres:** `context`, `date_debut`, `date_fin`, `demi_journee`
    * **Body de la requête:** `context=context&date_debut=date_debut&date_fin=date_fin&demi_journee=demi_journee`
    * **Exemple d'utilisation:** `context=malade&date_debut=2020-01-05&date_fin=2020-01-06&demi_journee=1`
    * **Résultat:** *html*

    
 * **`abs_groupe_etat`**
    * **Méthode:** GET
    * **Paramètres:** `group_ids`, `date_debut`, `date_fin`, `with_boursier=True`, `format=html`
    * **Routes:** `/api/absences/abs_group_etat/?group_ids=group_ids&date_debut=date_debut&date_fin=date_fin`
    * **Exemple d'utilisation:** `/api/absences/abs_group_etat/?group_ids=45&date_debut=2019-01-30&date_fin=2019-02-30`
    * **Résultat:** Liste des absences d'un ou plusieurs groupes entre deux dates.
    * **Exemple de résultat:** si `format="json"` cela donne:
      ```
       [ 
         {
           "boursier": "N",
           "nbabs": "9",
           "nbabsjust": "2",
           "nbabsnonjust": "7",
           "nbjustifs_noabs": "0",
           "nomprenom": "Mme Poisson Dodouce", 
           "etudid": "12345"
         }, 
         ... 
       ]
      ```
 
## Logos

  * **`liste des logos globaux`** 
    * **Méthode:** GET
    * **Paramètres:** `format` (json, xml), json par défaut
    * **Route :** `/api/logos`
    * **Exemple d'utilisation :** `/api/logos?format=xml`
    * **Résultat :** Liste des logos définis pour le site scodoc.
    * **Exemple de résultat:** `['header', 'footer', 'custom']`

    
  * **`récupération d'un logo global`** 
    * **Méthode:** GET
    * **Paramètres :** Aucun
    * **Route:** `/api/logos/<str:nom>`
    * **Exemple d'utilisation :** `/api/logos/header`
    * **Résultat :** l'image (format png ou jpg)
    
    
  * **`logo d'un département`** 
    * **Méthode:** GET
    * **Paramètres:** `format` (json, xml)
    * **Route :** `/api/departements/<str:dept>/logos`
    * **Exemple d'utilisation :** `/api/MMI/logos`
    * **Résultat :** Liste des logos définis pour le département visé.
    * **Exemple de résultat:** `['footer', 'signature', 'universite']`

    
  * **`récupération d'un logo global`** 
    * **Méthode:** GET
    * **Paramètres :** Aucun
    * **Route:** `/api/departements/<str:dept>/logos/<str:nom>`
    * **Exemple d'utilisation:** `/api/departements/MMI/logos/header`
    * **Résultat :** l'image (format png ou jpg)
    


##  En savoir plus 
Voir exemples d'utilisation de l'API en Python, dans `tests/api/`.