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

## Configuration de ScoDoc pour utiliser l'API

Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.

En général, il est recommandé de créer un rôle, de lui attribuer les permissions
que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle.

En ligne de commande, cela peut se faire comme suit (voir détail des commandes
[sur le guide de configuration](GuideConfig.md)).

```
# se connecter comme utilisateur scodoc
su - scodoc

# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici ScoView
flask edit-role LecteurAPI -a ScoView

# Créer un nouvel utilisateur avec ce rôle:
flask user-create lecteur_api LecteurAPI @all

# Ou bien, si on veut utiliser un compte existant:
#   associer notre rôle à un utilisateur
flask user-role lecteur_api -a LecteurAPI


# Au besoin, changer le mot de passe de l'utilisateur
# (on aura besoin de ce mot de passe dans la configuration du client d'API)
flask user-password lecteur_api
...
```

Si vous êtes intéressé par le développement, voir [la section sur les tests
unitaires de l'API](TestsScoDoc.md#tests-de-lapi-scodoc9).

## Essais avec HTTPie

[HTTPie](https://httpie.io/) est un client universel livre et gratuit très commode, disponible
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:
```
http -a USER:PASSWORD POST  'http://localhost:5000/ScoDoc/api/tokens'
```
Qui affiche:
```
HTTP/1.1 200 OK
Content-Length: 50
Content-Type: application/json
Date: Thu, 05 May 2022 04:29:33 GMT

{
    "token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
}
```
(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:
```
http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
```
qui affiche par exemple:
```
HTTP/1.1 200 OK
Content-Length: 151
Content-Type: application/json
Date: Thu, 05 May 2022 05:21:33 GMT

[
    {
        "acronym": "TAPI",
        "date_creation": "Wed, 04 May 2022 21:09:25 GMT",
        "description": null,
        "id": 1,
        "visible": true
    }
]
```

## Fonctions d'API ScoDoc 9

La documentation ci-dessous concerne la nouvelle API, disponible à partir de la 
version de ScoDoc 9.3.25.

### Accès à l'API REST

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).

#### 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, voir plus haut pour la ême chose avec la commande `http`):
  
  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"
}
```

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 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 objet inexistant.
  * [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur
    inconnue côté serveur.

## 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é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 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
                           
### Carte syntaxique

![carte_syntaxique](img/API_Chart.svg)#### Structure Département

### Tableau récapitulatif des point de l'API

Ce tableau est trié selon le type des informations retournées

* Un nom simple représente un seul objet de ce type;
* suivi de `+`désigne une forme 'longue' d'objet de ce type
* suivi de `*` désigne une liste de 0, 1 ou plusieurs objets du type;
* suivi de `#` désigne une liste d'entiers (les ids des objets du type).
* suivi de `:` puis d'un nom en majuscule indique une requête (POST) qui modifie les données de ScoDoc 

| Retour                     | Remarque                          | Méthode | Navigation                                                                                                         |
|:---------------------------|:----------------------------------|---------|--------------------------------------------------------------------------------------------------------------------|
| departement**`*`**         | tous les depts                    |GET      | [departements](http://localhost:8000/ScoDoc9API/**`**`#`**`**departements)                                                     |
| departement**`#`**         | tous les ids des depts            |GET      | [departements-ids](http://localhost:8000/ScoDoc9API/**`#`**departements-ids)                                             |
| departement                | recherche par id                  |GET      | [departement](http://localhost:8000/ScoDoc9API/**`#`**departement)                                                       |
| departement                | recherche par acronyme            |GET      | [departement](http://localhost:8000/ScoDoc9API/**`#`**departement)                                                       |
| formation**`*`**           | toutes les formations accessibles |GET      | [formations](http://localhost:8000/ScoDoc9API/**`#`**formations)                                                         |
| formation**`#`**           | ids des formations accessibles    |GET      | [formations-ids](http://localhost:8000/ScoDoc9API/**`#`**formations-ids)                                                 |
| formation                  | une formation                     |GET      | [formation](http://localhost:8000/ScoDoc9API/**`#`**formation)                                                           |
| export                     |                                   |GET      | [formation-export](http://localhost:8000/ScoDoc9API/**`#`**formation-export)                                             |
| export**`+`**              |                                   |GET      | [formation-export_with_ids](http://localhost:8000/ScoDoc9API/**`#`**formation-export_with_ids)                           |
| referentiel_competences    |                                   |GET      | [formation-referenciel_competences](http://localhost:8000/ScoDoc9API/**`#`**formation-referenciel_competences)           |
| formsemestre**`#`**        |                                   |GET      | [departement-formsemestres_ids](http://localhost:8000/ScoDoc9API/**`#`**departement-formsemestres_ids)                   |
| formsemestre**`*`**        |                                   |GET      | [departement-formsemestres_courants](http://localhost:8000/ScoDoc9API/**`#`**departement-formsemestres_courants)         |
| formsemestre**`*`**        |                                   |GET      | [formsemestre-query](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-query)                                         |
| formsemestre**`*`**        |                                   |GET      | [etudiant-formsemestres](http://localhost:8000/ScoDoc9API/**`#`**etudiant-formsemestres)                                 |
| formsemestre               |                                   |GET      | [formsemestre](http://localhost:8000/ScoDoc9API/**`#`**formsemestre)                                                     |
| moduleimpl                 |                                   |GET      | [moduleimpl](http://localhost:8000/ScoDoc9API/**`#`**moduleimpl)                                                         |
| partition**`*`**           |                                   |GET      | [formsemestre-partitions](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-partitions)                               |
| partition                  |                                   |GET      | [partition](http://localhost:8000/ScoDoc9API/**`#`**partition)                                                           |
| partition:CREATE           |                                   |POST     | [formsemestre-partition-create](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-partition-create)                   |
| partition:EDIT             |                                   |POST     | [partition-edit](http://localhost:8000/ScoDoc9API/**`#`**partition-edit)                                                 |
| partition:ACTION           |                                   |POST     | [formsemestre-partitions-order](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-partitions-order)                   |
| partition:DELETE           |                                   |POST     | [partition-delete](http://localhost:8000/ScoDoc9API/**`#`**partition-delete)                                             |
| partition:ACTION           |                                   |POST     | [partition-remove_etudiant](http://localhost:8000/ScoDoc9API/**`#`**partition-remove_etudiant)                           |
| group:CREATE               |                                   |POST     | [partition-group-create](http://localhost:8000/ScoDoc9API/**`#`**partition-group-create)                                 |
| group:EDIT                 |                                   |POST     | [group-edit](http://localhost:8000/ScoDoc9API/**`#`**group-edit)                                                         |
| group:ACTION               |                                   |POST     | [partition-groups-order](http://localhost:8000/ScoDoc9API/**`#`**partition-groups-order)                                 |
| group:DELETE               |                                   |POST     | [group-delete](http://localhost:8000/ScoDoc9API/**`#`**group-delete)                                                     |
| group*                     |                                   |POST     | [etudiant-formsemestre-groups](http://localhost:8000/ScoDoc9API/**`#`**etudiant-formsemestre-groups)                     |
| group:ACTION               |                                   |GET      | [group-set_etudiant](http://localhost:8000/ScoDoc9API/**`#`**group-set_etudiant)                                         |
| group:ACTION               |                                   |POST     | [group-remove_etudiant](http://localhost:8000/ScoDoc9API/**`#`**group-remove_etudiant)                                   |
| etudiant**`*`**            | tous les étudiants                |GET      | [etudiants](http://localhost:8000/ScoDoc9API/**`#`**etudiants)                                                           |
| etudiant**`*`**            | recherche par etudid, nip ou i    |GET      | [etudiants-clé](http://localhost:8000/ScoDoc9API/**`#`**etudiants-clé)                                                   |
| etudiant**`*`**            | les étudiants actuels             |GET      | [etudiants-courant](http://localhost:8000/ScoDoc9API/**`#`**etudiants-courant)                                           |
| etudiant**`*`**            |                                   |GET      | [departement-etudiants](http://localhost:8000/ScoDoc9API/**`#`**departement-etudiants)                                   |
| etudiant**`*`**            |                                   |GET      | [formsemestre-etudiants](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-etudiants)                                 |
| etudiant**`*`**            |                                   |GET      | [formsemestre-etudiants-defaillants](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-etudiants-defaillants)         |
| etudiant**`*`**            |                                   |GET      | [formsemestre-etudiants-demissionnaires](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-etudiants-demissionnaires) |
| etudiant**`*`**            |                                   |GET      | [group-etudiants](http://localhost:8000/ScoDoc9API/**`#`**group-etudiants)                                               |
| etudiant**`*`**            |                                   |GET      | [group-etudiants-query](http://localhost:8000/ScoDoc9API/**`#`**group-etudiants-query)                                   |
| etudiant                   |                                   |GET      | [etudiant](http://localhost:8000/ScoDoc9API/**`#`**etudiant)                                                             |
|                            |                                   |GET      | [jury-formsemestre-decisions_jury](http://localhost:8000/ScoDoc9API/**`#`**jury-formsemestre-decisions_jury)             |
| bulletin**`*`**            |                                   |GET      | [formsemestre-bulletin](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-bulletin)                                   |
| bulletin                   |                                   |GET      | [etudiant-formsemestre-bulletin](http://localhost:8000/ScoDoc9API/**`#`**etudiant-formsemestre-bulletin)                 |
| programme                  |                                   |GET      | [formsemestre-programme](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-programme)                                 |
|                            |                                   |GET      | [formsemestre-etat_evals](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-etat_evals)                               |
|                            |                                   |GET      | [formsemestre-resultats](http://localhost:8000/ScoDoc9API/**`#`**formsemestre-resultats)                                 |
| evaluation*                |                                   |GET      | [evaluations](http://localhost:8000/ScoDoc9API/**`#`**evaluations)                                                       |
| note*                      |                                   |GET      | [evaluation-notes](http://localhost:8000/ScoDoc9API/**`#`**evaluation-notes)                                             |
| user                       |                                   |GET      | [user](http://localhost:8000/ScoDoc9API/**`#`**user)                                                                     |

###  **Départements**


| attribut         | type    | commentaire                            |
|:-----------------|:--------|:---------------------------------------|
| _id_             | int     | identifiant 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                               |

#### **departements**
* **Méthode:** GET
* **Routes:** `/departements`
* **Exemple d'utilisation:** `/api/departements`
* **Résultat:** Liste de tous les départements (visibles ou non).
* **Exemple de résultat:**  [departements.json](samples/sample_departements.json.md)
  
#### **departements-ids** 
  * **Méthode:** GET
  * **Routes:** `/departements_ids`
  * **Résultat:** Liste des id départements (visibles ou non).
  * **Exemple de résultat:**
      ```json
      [ 1888, 999, 165 ]
      ```

#### **departement** 
* **Méthode:** GET
* **Routes:**
    * `/departement/id/<int:dept_id>`
    * `/departement/<string:dept>`
* **Résultat:** Un département
* **Exemple de résultat:**  [departement.json](samples/sample_departement.json.md)

### **Formation**
#### Structure Formation
| attribut                    | type        | commentaire                                       |
|:----------------------------|:------------|:--------------------------------------------------|
| _dept_id_                   | int         | _redondant avec departement.id ?_                 |
| _acronyme_                  | string      |                                                   |
| _titre_                     | string      | _URL encoded ?_                                   |
| _version_                   | int         |                                                   |
| _type_parcours_             | int         |                                                   |
| _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  |
| _code_specialité_           | string      |                                                   |
| _departement_               | Département | _pour `/formations` mais pas pour `/formation` ?_ |
|  _formation_id_             |             | _redondant avec id ?_                             |

#### **`formations`**
* **Méthode:** GET
* **Routes:** `/formations`
* **Exemple d'utilisation:** `/ScoDoc/api/formations`
* **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:** Liste des ids de toutes les formations (tous départements
  accessibles).
* **Exemple de résultat:** 
```json
[17, 99, 32]
```

#### **`formation`**
* **Méthode:** GET
* **Paramètres:** `formation_id`
* **Routes:** `/formation/<int:formation_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formation/1`
* **Résultat:** Description de la formation.
* **Exemple de résultat:**  [formation.json](samples/sample_formation.json.md)

### **Formsemestre**

Les sessions de formation (qu'elles durent une année ou un mois) sont représentées par les `formsemestre`.

#### Note sur les identifiants de formsemestre
Le `session_id` peut être utilisé pour identifier de façon prévisible et
(presque) unique un formsemestre) 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...) (acronyme 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) dans la "formation" (le 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).

#### **departement-formsemestres_ids**
* **Méthode:** GET
* **Paramètres:** `dept`
* **Routes:**
    * `/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é.
* **Exemple de résultat:**
  ```[ 28, 99, 3 ]```

#### **departement-formsemestres-courants**
* **Méthode:** GET
* **Paramètres:** `dept_id`
* **Routes:**
    * `/departement/id/<int:dept_id>/formsemestres_courants`
    * `/departement/<string:dept>/formsemestres_courants`
* **Exemple d'utilisation:** `/api/departement/MMI/formsemestres_courants`
* **Résultat:** Liste des formsemestres en cours d'un département donné.
* **Exemple de résultat:** [departement-formsemestres-courants.json](samples/sample_departement-formsemestres-courants.json.md)

#### **formsemestres-query**
* **Méthode:** GET
* **Paramètres:** aucun
* **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:** 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**
* **Méthode:** GET
* **Paramètres:** `etudid`, `nip`, `ine`
* **Routes:** :
    * `/etudiant/etudid/<int:etudid>/formsemestres` ou
    * `/etudiant/nip/<string:nip>/formsemestres` ou
    * `/etudiant/ine/<string:ine>/formsemestres`
* **Exemple d'utilisation:** `/etudiant/ine/1/formsemestres`
* **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**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Route:** `/formsemestre/<int:formsemestre_id>`
* **Exemple d'utilisation:** `/api/formsemestre/1`
* **Résultat:** Description du formsemestre.
* **[Exemple de résultat:](samples/sample_formsemestre.json.md)**

### **Moduleimpl**

Le moduleimpl est la mise en place d'un module dans un formsemestre (avec son
responsable et ses enseignants).

#### **`moduleimpl`**
* **Méthode:** GET
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/moduleimpl/<int:moduleimpl_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/formation/moduleimpl/1`
* **Résultat:** Description du moduleimpl.
* **Exemple de résultat:** [moduleimpl.json](samples/sample_moduleimpl.json.md)

### **Partition**

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.

#### **`formsemestre-partitions`**
* **Méthode: GET**
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/partitions`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/911/partitions`
* **Résultat:** Liste de toutes les partitions d'un formsemestre.
* **Exemple de résultat:** [formsemestre-partitions.json](samples/sample_formsemestre-partitions.json.md)

#### **`partition`**
* **Méthode: GET**
* **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1963`
* **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`**
* **Méthode: POST**
* **Paramètres:** `formsemestre_id`
* **Data:** `{ "partition_name" : <string> }`
* **Routes:** `/formsemestre/<int:formsemestre_id>/partition/create`
>`{ "partition_name" : "PART" }`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/944/partition/create`
* **Résultat:** Crée une nouvelle partition dans un formsemestre.
* **[Exemple de résultat:](samples/sample_formsemestre-partition-create.json.md)**

#### **`partition-edit`**
* **Méthode: POST**
* **Paramètres:** `partition_id`
* **Data:** `{ partition_name : <string> }`
* **Routes:** `/partition/<int:partition_id>/edit`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/2047/edit`
>`{ "partition_name" : "PART4" }`
* **Résultat:** Renomme une partition
* **[Exemple de résultat](samples/sample_partition-edit.json.md)**

#### **`formsemestre-partition-order`**
* **Méthode: POST**
* **Paramètres:** `formsemestre_id`
* **Data:** `[ <int:partition_id1>, <int:partition_id2>, ... ]`
* **Routes:** `/formsemestre/<int:formsemestre_id>/partition/order`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/944/partition/order`
>`[ 2048, 2054 ]`
* **Résultat:** Spécifie l'ordre des partitions d'un formsemestre.
* **[Exemple de résultat:](samples/sample_formsemestre-partition-order.json.md)**

#### **`partition-delete`**
* **Méthode: POST**
* **Paramètres:** `partition_id`
* **Routes:** `/partition/<int:partition_id>/delete`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/2047/delete`
* **Résultat:** Supprime une partition.
* **[Exemple de résultat](samples/sample_partition-delete.json.md)**

#### **`partition-remove_etudiant`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`***
* **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:** Retire un étudiant des groupes de la partition.
* **[Exemple de résultat](samples/sample_partition-remove_etudiant.json.md)**

### **Groupe**

#### **`partition-group-create`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`***
* **Paramètres:** `partition_id`
* **Data:** `{ group_name : <string> }`
* **Routes:** `/partition/<int:partition_id>/create`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/create`
>`{ "group_name" : "A" }`
* **Résultat:** Crée un groupe dans une partition.
* **[Exemple de résultat](samples/sample_formsemestre-partition-create.json.md)**

#### **`group-edit`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`***
* **Paramètres:** `group_id`
* **Data:** `{ group_name : <string> }`
* **Routes:** `/group/<int:group_id>/edit`
* **Exemple d'utilisation:** `/ScoDoc/api/group/4581/edit`
>`{ "group_name" : "nouveau" }`
* **Résultat:** Renomme un groupe.
* **[Exemple de résultat](samples/sample_group-edit.json.md)**

#### **`partition-groups-order`**
* **Méthode: POST**
* **Paramètres:** `partition_id`
* **Data:** `[ <int:group_id1>, <int:group_id2>, ... ]`
* **Routes:** `/partition/<int:partition_id>/groups/order`
* **Exemple d'utilisation:** `/ScoDoc/api/partition/1962/groups/order`
>`[ 4383, 4379, 4380, 4381, 4382, 4384 ]`
* **Résultat:** Spécifie l'ordre des groupes d'une partition.
* **[Exemple de résultat:](samples/sample_partition-groups-order.json.md)**

#### **`group-delete`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`***
* **Paramètres:** `group_id`
* **Routes:** `/group/<int:group_id>/delete`
* **Exemple d'utilisation:** `/ScoDoc/api/group/4581/delete`
* **Résultat:** Supprime un groupe.
* **[Exemple de résultat](samples/sample_group-delete.json.md)**

#### **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`
* **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)

#### **`group-set_etudiant`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`***
* **Paramètres:** `group_id`, `etudid`
* **Routes:** `/group/<int:group_id>/set_etudiant/<int:etudid>`
* **Exemple d'utilisation:** `/ScoDoc/api/group/4085/set_etudiant/12108`
* **Résultat:** Affecte un étudiant dans un groupe.
* **[Exemple de résultat](samples/sample_group-set_etudiant.json.md)**

#### **`group-remove_etudiant`**
* **Méthode: POST**
* **Permission: `ScoEtudChangeGroups`***
* **Paramètres:** `group_id`, `etudid`
* **Routes:** `/group/<int:group_id>/remove_etudiant/<int:etudid>`
* **Exemple d'utilisation:** `/ScoDoc/api/group/4085/remove_etudiant/12108`
* **Résultat:** Retire un étudiant d'un groupe.
* **[Exemple de résultat](samples/sample_group-remove_etudiant.json.md)**

### **Etudiant**
#### **`etudiants`**
* **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. 
* **Exemple de résultat:** [tous-les-etudiant.json](samples/sample_tous-les-etudiants.json.md)

#### **`etudiants-clef`**
* **Méthode:** GET
* **Paramètres:**  `etudid`, `nip`, `ine`
* **Routes:** `/etudiants/etudid/<int:etudid>` ou `/etudiants/nip/<string:nip>` ou `/etudiants/ine/<string:ine>`
* **Exemple d'utilisation:** `/api/etudiants/nip/1`
* **Résultat:** Info sur le ou les étudiants correspondants.
  Comme [`/etudiant`](ScoDoc9API.md#etudiant) mais renvoie toujours une liste.
  Si non trouvé, liste vide, pas d'erreur.
  Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a
  été inscrit dans plusieurs départements, on a plusieurs objets (1 par
  dept.).
* **Exemple de résultat:** [etudiants.json](samples/sample_etudiants.json.md)

#### **`etudiants-courants`**
* **Méthode:** GET
* **Routes:**
    * `/etudiants/courants`
    * `/etudiants/courants/long`
* **Exemple d'utilisation:** `/api/etudiants/courants`
* **Résultat:** Liste des étudiants inscrits dans un formsemestre
  actuellement en cours. Avec `/long`, donne tous les attributs de
  l'étudiants (plus lent).
* **Exemple de résultat:** [etudiants-courants.json](samples/sample_etudiants-courants.json.md)

#### **departement-etudiants**
* **Méthode:** GET
* **Paramètres:** `dept`, `dept_id`
* **Routes:**
    * `/departement/id/<int:dept_id>/etudiants`
    * `/departement/<string:dept>/etudiants`
* **Exemple d'utilisation:** `/api/departement/MMI/etudiants`
* **Résultat:** liste tous les étudiants (passés ou présents) d'un département.
  On peut spécifier l'acronyme du département ("MMI") ou son id (un entier).
  Attention, la liste peut être longue: requête coûteuse à éviter.
* **Exemple de résultat:**
    ```json
    [
      {
            "civilite": "M", // M, F ou X
            "ine": "7899X61616",
            "code_nip": "F6777H88",
            "date_naissance": null,
            "email": "toto@toto.fr",
            "emailperso": null,
            "etudid": 18,
            "nom": "MOREL", // en majuscules
            "prenom": "JACQUES"
      },
      ...
    ]
    ```

#### **formsemestre-etudiants**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/etudiants` XXX voir si
  filtrage par état (dem, def, ...)
* **Route:**
    * `/formsemestres/etudiants`
    * `/formsemestres/etudiants/demissionnaires`
    * `/formsemestres/etudiants/defaillants`
* **Exemple d'utilisation:** `/api/formsemestre/1/etudiants`
* **Résultat:** Etudiants d'un formsemestre spécifié par son id. Liste est restreinte aux étudiants démissionnaires/défaillants si l'option correspondante est ajoutée au chemin
* **Exemple de résultat:**  [formsemestre-etudiants.json](samples/sample_formsemestre-etudiants.json.md)

#### **formsemestre-etudiants-etat**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`, `etat` (par défaut égal à "I" pour les étudiants inscrits)
* **Résultat:** les étudiants inscrits à ce semestres XXX préciser état
  (DEM, DEF))

#### **`group-etudiants`**
* **Méthode: GET**
* **Paramètres:** `group_id`
* **Routes:** `/group/<int:group_id>/etudiants`
* **Exemple d'utilisation:** `/ScoDoc/api/group/1/etudiants`
* **Résultat:** Retourne la liste des étudiants dans un groupe.
* **Exemple de résultat:** [group-etudiants.json](samples/sample_group-etudiants.json.md)

#### **`groups-etudiants-query`**
* **Méthode: GET**
* **Paramètres:** `group_id`
* **Query string:** `etat` ('I', 'D' ou 'DEF')
* **Routes:** `/group/<int:group_id>/etudiants/query`
* **Exemple d'utilisation:** `/ScoDoc/api/group/1/etudiants/query?etat=I`
* **Résultat:** Retourne la liste des étudiants dans un groupe.
* **Exemple de résultat:** [group-etudiants-query.json](samples/sample_group-etudiants-query.json.md)

#### **`etudiant`**
* **Méthode:** GET
* **Paramètres:**  `etudid`, `nip`, `ine`
* **Routes:**
    * `/etudiant/etudid/<int:etudid>` ou
    * `/etudiant/nip/<string:nip>` ou
    * `/etudiant/ine/<string:ine>`
* **Exemple d'utilisation:** `/api/etudiant/nip/1`
* **Résultat:** Retourne les informations sur l'étudiant correspondant à
  l'id passé en paramètres.
  Les codes INE et NIP sont uniques au sein d'un département.
  Si plusieurs objets étudiant ont le même code, on ramène le plus récemment inscrit.
* **Exemple de résultat:**  [etudiant.json](samples/sample_etudiant.json.md)

### Programme, Référentiel

#### **`formation-export`**
* **Méthode:** GET
* **Paramètres:** `formation_id`, `export_ids` (False par défaut. Ajouter `/with_ids` pour le passer à True)
* **Routes:**
    * `/formation/<int:formation_id>/export`
    * `/formation/<int:formation_id>/export_with_ids`
* **Exemple d'utilisation:** `/ScoDoc/api/formation/formation_export/1`
* **Résultat:** Retourne la formation, avec UE, matières, modules
* **Exemple de résultat:** [formation-export.json](samples/sample_formation-referentiel_competences.json.md)

#### **`formation-referentiel_competences`**
* **Méthode:** GET
* **Paramètres:** `formation_id`
* **Routes:** `/formation/<int:formation_id>/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_)
* **Exemple de résultat:** [formation-referentiel_competences.json](samples/sample_formation-referentiel_competences.json.md)

### **Bulletin, Evaluations, Notes**
#### **formsemestre-bulletins**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Route:** `/formsemestre/<int:formsemestre_id>/bulletins
* **Exemple d'utilisation:** `/api/formsemestre/1/bulletins`
* **Résultat:** Bulletins d'un formsemestre spécifié par son id.
* **Exemple de résultat:** [formsemestre-bulletins.json](samples/sample_formsemestre-bulletins.json.md)

#### **etudiant-formsemestre-bulletin**
* **Méthode:** GET
* **Paramètres:**  `formsemestre_id`, `etudid`, `nip`, `ine`
* **Routes:**
  `/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf]`
  ou `/etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf]`
  ou `/etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf]`

On peut spécifier le format: `long`ou `short`, et indiquer si l'on veut le
bulletin PDF.
* **Exemple d'utilisation:** `/etudiant/nip/1/formsemestre/1/bulletin`
* **Résultat:** Bulletin de l'étudiant dans le formsemestre.
  Deux versions disponibles `long` et `short` (par défaut `long` ajoutez
  `/short` pour la version plus courte).
* **Exemple de résultat:**  [bulletin-formsemestre-etudiant.json](samples/sample_bulletin-formsemestre-etudiant.json.md)

#### **formsemestre-programme**
* **Méthode:** GET
* **Paramètres:** `dept`, `formsemestre_id`
* **Routes:** `/formsemestre/<int:formsemestre_id>/programme`
* **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/programme`
* **Résultat:** Retourne la liste des UEs, modules, ressources et SAE d'un semestre.
* **Exemple de résultat:** [formsemestre-programme.json](samples/sample_formsemestre-programme.json.md)

#### **formsemestre-etat_evals**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **Route:** `/formsemestre/<int:formseemestre_id>/etat_evals`
* **Exemple d'utilisation:** `/api/formsemestre/1/etat_evals`
* **Résultat:** informations sur les évaluations d'un formsemestre spécifié par son id.
* **Exemple de résultat:** [formsemestre-etat-eval.json](samples/sample_formsemestre-etat_evals.json.md)

#### **formsemestre-resultats**
* **Méthode:** GET
* **Paramètres:** `formsemestre_id`
* **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 formatées en chaînes. Si format=raw,
valeurs numériques mais pas JSON compliant à cause des _NaN_.

* **Exemple de résultat:**

#### **`evaluations`**
* **Méthode:** GET
* **Paramètres:** `moduleimpl_id`
* **Routes:** `/moduleimpl/<int:moduleimpl_id>/evaluations`
* **Exemple d'utilisation:** `/ScoDoc/api/moduleimpl/1/evaluations`
* **Résultat:** Retourne la liste des évaluations à partir de l'id d'un
  moduleimpl (quel que soit leur statut).
* **[Exemple de résultat](samples/sample_moduleimpl-evaluations.json.md)**

#### **`evaluations/notes`**
* **Méthode**: GET
* **Paramètres**: `evaluation_id`
* **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:** TODO XXX

### **User**

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

XXX vérifier si on supporte XML et pour qui ?

#### **`logo`**
* **Méthode:** GET
* **Paramètres :** Aucun
* **Route:** `/logos/<string:nom>`
* **Exemple d'utilisation :** `/ScoDoc/api/logo/header`
* **Résultat :** l'image (format png ou jpg)

#### **`departement-logos`**
* **Méthode:** GET
* **Paramètres:** `format` (json, xml)
* **Route :** `/departements/<string:dept>/logos`
* **Exemple d'utilisation :** `/ScoDoc/api/departements/MMI/logos`
* **Résultat :** Liste des noms des logos définis pour le département visé.
* **Exemple de résultat:** `['footer', 'signature', 'universite']`

#### **`departement-logo`**
* **Méthode:** GET
* **Paramètres :** Aucun
* **Route:** `/departements/<string:dept>/logo/<string:nom>`
* **Exemple d'utilisation:** `/ScoDoc/api/departements/MMI/logos/header`
* **Résultat :** l'image (format png ou jpg)

-------------------------------------------------------------------------------------------------------------------------------------------------------

## **Réserve**
### Étudiants inscrits et bulletins
#### * **`formsemestre-bulletins`**
  * **Méthode:** GET
  * **Paramètres:** `formsemestre_id`
  * **Routes:** `/formsemestre/<int:formsemestre_id>/bulletins`
  * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/bulletins`
  * **Résultat:**  tous les bulletins d'un formsemestre.
  * **[Exemple de résultat](samples/sample_formsemestre-bulletins.json.md)**

#### **formsemestre-etat_evals**
  * **Méthode:** GET
  * **Paramètres:** `formsemestre_id`
  * **Routes:** `/formsemestre/<int:formsemestre_id>/etat_evals`
  * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/etat_evals`
  * **Résultat:** Retourne les informations sur l'état des évaluations d'un semestre donné
  * **Exemple de résultat:** [formsemestre-etat_evals.json](samples/sample_formsemestre-etat_evals.json.md)
    
#### **`formsemestre-decision_jury`**
  * **Méthode:** GET
  * **Paramètres:** `formsemestre_id`
  * **Routes:** `/formsemestre/<int:formsemestre_id>/decision_jury`
  * **Exemple d'utilisation:** `/ScoDoc/api/formsemestre/1/jury`
  * **Résultat:** Retourne le récapitulatif des décisions jury
  * **Exemple de résultat:**
      ```
      XXX A COMPLETER
      ```

###  Évaluations


###  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`, `nip`, `ine`
  * **Routes:** `/absences/etudid/<int:etudid>`
  * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/123456`
  * **Résultat:** Retourne la liste des absences d'un étudiant donné
  * **Exemple de résultat:**
    ```
    [
      {
        "jour": "2022-04-15",
        "matin": true,
        "estabs": true,
        "estjust": true,
        "description": "Retard bus",
        "begin": "2022-04-15 08:00:00",
        "end": "2022-04-15 11:59:59"
      },
      {
        ...
      }
    ]
    ```
       
#### **`absences/just`**
     
  * **Méthode:** GET
  * **Paramètres:**  `etudid`
  * **Routes:** `/absences/etudid/<int:etudid>/just`
  * **Exemple d'utilisation:** `/ScoDoc/api/absences/etudid/1/just`
  * **Résultat:** Retourne la liste des absences justifiées d'un étudiant donné
  * **Exemple de résultat:**
    ```
    [
      {
        "jour": "2022-04-15",
        "matin": true,
        "estabs": true,
        "estjust": true,
        "description": "Retard bus",
        "begin": "2022-04-15 08:00:00",
        "end": "2022-04-15 11:59:59"
      },
      {
        ...
      }
    ]
    ```

    
#### **`abs_groupe_etat`**
    
  * **Méthode:** GET
  * **Paramètres:** `group_ids`, `date_debut`, `date_fin`,
  * **Routes:** `/absences/abs_group_etat/<int:group_id>` ou `/absences/abs_group_etat/group_id/<in:group_id>/date_debut/<date:date_debut>/date_fin/<date:date_fin>`
  * **Exemple d'utilisation:** `/ScoDoc/api/absences/abs_group_etat/1`
  * **Résultat:** Liste des absences d'un groupe entre deux dates.
  * **Exemple de résultat:**
      ```
      XXX A COMPLETER XXX with_boursier ??

  * XXX ajouter méthode(s) de set abs
        ```
      

### Jury

#### **`jury_preparation`**

  * **Méthode:** GET
  * **Paramètres:** `formsemestre_id`
  * **Routes:** `/jury/formsemestre/<int:formsemestre_id>/preparation_jury`
  * **Exemple d'utilisation:** `/ScoDoc/api/jury/formsemestre/1/preparation_jury`
  * **Résultat:** Retourne la feuille de préparation du jury
  * **Exemple de résultat:**
      ```
      XXX A COMPLETER
      ```
      
#### **`jury_decisions`**

  * **Méthode:** GET
  * **Paramètres:** `formsemestre_id`
  * **Routes:** `/jury/formsemestre/<int:formsemestre_id>/decisions_jury`
  * **Exemple d'utilisation:** `/ScoDoc/api/jury/formsemestre/1/decisions_jury`
  * **Résultat:** Retourne les décisions du jury suivant un formsemestre donné
  * **Exemple de résultat:**
      ```
      XXX A COMPLETER
      ```


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

## 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.