forked from ScoDoc/DocScoDoc
Ajouts détails sur config. d'un utilisateur pour l'API
This commit is contained in:
parent
42f4fe05ff
commit
5b1ad81249
@ -1,5 +1,5 @@
|
||||
|
||||
# API pour ScoDoc 9
|
||||
## 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.
|
||||
@ -24,45 +24,51 @@ Les objets ScoDoc manipulables sont identifiés par des id.
|
||||
|
||||
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
|
||||
## Configuration de ScoDoc pour utiliser l'API
|
||||
|
||||
L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md)
|
||||
Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.
|
||||
En ligne de commande, cela peut se faire comme suit (voir détail des commandes
|
||||
[sur le guide de configuration](GuideConfig.md)).
|
||||
|
||||
- `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`)
|
||||
```
|
||||
# se connecter comme utilisateur scodoc
|
||||
su - scodoc
|
||||
|
||||
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.
|
||||
# Créer un rôle
|
||||
flask create-role LecteurAPI
|
||||
# Lui donner les droits nécessaires: ici APIView
|
||||
flask edit-role LecteurAPI -a APIView
|
||||
|
||||
Note:
|
||||
- `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API.
|
||||
# Créer un nouvel utilisateur avec ce rôle:
|
||||
flask user-create lecteur_api LecteurAPI @all
|
||||
|
||||
# Fonctions d'API ScoDoc 9 (work in progress)
|
||||
# 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
|
||||
...
|
||||
```
|
||||
|
||||
## 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.
|
||||
La documentation ci-dessous concerne la **future** version de ScoDoc (9.3, avec
|
||||
parties expérimentales progressivement mises en production à partir de 9.2.12).
|
||||
|
||||
## Accès à l'API REST
|
||||
### Accès à l'API REST
|
||||
|
||||
Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
|
||||
|
||||
### Authentification
|
||||
#### 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
|
||||
@ -87,7 +93,7 @@ La réponse doit ressembler à ceci:
|
||||
Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple
|
||||
complet en python d'interrogation de l'API.
|
||||
|
||||
### Codes HTTP
|
||||
#### 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.
|
||||
@ -105,7 +111,7 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
|
||||
* [503](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/503) : L'API est momentanément indisponible, réessayez dans quelques minutes.
|
||||
|
||||
|
||||
## Départements
|
||||
### Départements
|
||||
* **`departements`**
|
||||
* **Méthode:** GET
|
||||
* **Paramètres:** `viewable` (optionnel, si faux liste aussi les
|
||||
@ -142,7 +148,7 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
|
||||
|
||||
* XXX obtenir la liste des référentiels
|
||||
|
||||
## Etudiants
|
||||
### Etudiants
|
||||
* **`etud_dept`**
|
||||
* **Méthode:** GET
|
||||
* **Paramètres:** `code_nip`
|
||||
@ -452,7 +458,7 @@ formsemestre_id": "SEM12345",
|
||||
}
|
||||
```
|
||||
|
||||
## UE
|
||||
### UE
|
||||
* **`UEs`**
|
||||
* **Méthode:** GET
|
||||
* **Paramètres:** `dept`, `̀semestre`
|
||||
@ -463,7 +469,7 @@ formsemestre_id": "SEM12345",
|
||||
|
||||
|
||||
|
||||
## Semestres de formation
|
||||
### 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`**
|
||||
@ -493,7 +499,7 @@ Les sessions de formation (dénommées "semestres" même si elles durent une ann
|
||||
]
|
||||
```
|
||||
|
||||
### Note sur les identifiants de sessions
|
||||
#### 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
|
||||
@ -514,7 +520,7 @@ informations suivantes:
|
||||
**Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI)
|
||||
|
||||
|
||||
## Modules de formation
|
||||
### 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.
|
||||
|
||||
@ -530,7 +536,7 @@ On peut récupérer soit un module par son id, soit la listes des modules d'un s
|
||||
|
||||
|
||||
|
||||
## Groupes et partitions
|
||||
### 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
|
||||
@ -664,7 +670,7 @@ d'un nombre quelconque de groupes d'étudiants.
|
||||
TODO: à changer, passer les paramètres dans le corps de la requête
|
||||
|
||||
|
||||
## Bulletins de notes
|
||||
### Bulletins de notes
|
||||
* **`evaluations`**
|
||||
* **Méthode:** GET
|
||||
* **Paramètres:** `moduleimpl_id`
|
||||
@ -702,7 +708,7 @@ d'un nombre quelconque de groupes d'étudiants.
|
||||
TODO vérifier et passer les valeurs dans le corps.
|
||||
|
||||
|
||||
## Absences
|
||||
### 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.
|
||||
|
||||
|
||||
@ -762,7 +768,7 @@ d'un nombre quelconque de groupes d'étudiants.
|
||||
]
|
||||
```
|
||||
|
||||
## Logos
|
||||
### Logos
|
||||
|
||||
* **`liste des logos globaux`**
|
||||
* **Méthode:** GET
|
||||
@ -798,6 +804,33 @@ d'un nombre quelconque de groupes d'étudiants.
|
||||
* **Résultat :** l'image (format png ou jpg)
|
||||
|
||||
|
||||
|
||||
## En savoir plus
|
||||
### 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user