API REST #149

Closed
opened 2021-10-05 15:43:02 +02:00 by yann · 16 comments
Contributor

WIP : définition des points d'accés à l'API REST. Elle sera accessible à l'adresse https://scodoc.monsite.tld/ScoDoc/api/fonction

le transfert d'informations se fera au format JSON

fonction méthode paramètres exemple exemple résultat
etud_dept GET code_nip /api/etud_dept/123 [ {exist: true, dept: "GEII", id: 987, dept_id: 3} ]
liste des étudiants avec le code NIP donné triée par ordre d'inscription décroisant
etud_info GET etud_id /api/etud_info/987 {
"nom": "Mutis",
"sexe": "M.",
"email": "alvaro.mutis@example.com",
"prenom": "ALVARO",
"nomprenom": "M. Alvaro MUTIS",
"insemestre": [
{
"etat": "I",
"formsemestre_id": "SEM12781",
"date_fin": "2010-07-30",
"date_debut": "2010-01-25"
},
{
"etat": "I",
"formsemestre_id": "SEM8396",
"date_fin": "2009-01-16",
"date_debut": "2008-09-01"
}
],
"etudid": "EID8768",

"domicile": "2 Rue Madame",
"villedomicile": "Paris",
"telephonemobile": ""
}
etud_bul GET etud_id
sem_id
/api/etud_bul/987/12 cf formsemestre_bulletinetud de l'ancienne API
sem_info GET sem_id /api/sem_info/12 [ {
"titre": "DUT Génie Electrique et Informatique Industrielle",
"date_debut": "01/09/2021",
"date_fin": "02/02/2022",
"modalite": "FI",
"sem_id_txt": "S3",
"titre_num": "DUT Génie Electrique et Informatique Industrielle semestre 3",
"anneescolaire": "2021 - 2022",
"periode": 1,
"titreannee": "DUT Génie Electrique et Informatique Industrielle semestre 3 FI 2021-2022"
} ]
photo GET etud_id /api/photo/123
/api/photo/123/small
WIP : définition des points d'accés à l'API REST. Elle sera accessible à l'adresse https://scodoc.monsite.tld/ScoDoc/api/fonction le transfert d'informations se fera au format JSON | fonction | méthode | paramètres | exemple | exemple résultat | | -------- | -------- | -------- | -------- | -------- | -------- | | etud_dept | GET | code_nip | /api/etud_dept/123 | [ {exist: true, dept: "GEII", id: 987, dept_id: 3} ]<br/>liste des étudiants avec le code NIP donné triée par ordre d'inscription décroisant | | etud_info | GET | etud_id | /api/etud_info/987 | {<br/> "nom": "Mutis", <br/> "sexe": "M.", <br/> "email": "alvaro.mutis@example.com", <br/> "prenom": "ALVARO",<br/> "nomprenom": "M. Alvaro MUTIS", <br/> "insemestre": [<br/> {<br/> "etat": "I", <br/> "formsemestre_id": "SEM12781", <br/> "date_fin": "2010-07-30", <br/> "date_debut": "2010-01-25"<br/> }, <br/> {<br/> "etat": "I", <br/> "formsemestre_id": "SEM8396", <br/> "date_fin": "2009-01-16", <br/> "date_debut": "2008-09-01"<br/> }<br/> ], <br/> "etudid": "EID8768", <br/><br/> "domicile": "2 Rue Madame", <br/> "villedomicile": "Paris", <br/> "telephonemobile": ""<br/>} | | etud_bul | GET | etud_id<br/>sem_id | /api/etud_bul/987/12 | cf formsemestre_bulletinetud de l'[ancienne API](https://scodoc.org/ScoDocAPI/) | | sem_info | GET | sem_id | /api/sem_info/12 | [ { <br/>"titre": "DUT Génie Electrique et Informatique Industrielle",<br/>"date_debut": "01/09/2021",<br/>"date_fin": "02/02/2022",<br/>"modalite": "FI",<br/>"sem_id_txt": "S3",<br/>"titre_num": "DUT Génie Electrique et Informatique Industrielle semestre 3",<br/>"anneescolaire": "2021 - 2022",<br/>"periode": 1,<br/>"titreannee": "DUT Génie Electrique et Informatique Industrielle semestre 3 FI 2021-2022"<br/>} ] | | photo | GET | etud_id | /api/photo/123<br/>/api/photo/123/small | |
Contributor

(en cours de modification)

fonction méthode paramètres champs résultat exemple exemple résultat
formation_list GET dept (facultatif) formation_id
acronyme
titre
...
/api/formation_list

/api/formation_list?dept=GEII
{ "id": 1,"dept_id": 1,"acronyme": "BUT GEII", "titre": "BUT G\u00e9nie Electrique et Informatique Industrielle", "titre_officiel": "BUT G\u00e9nie Electrique et Informatique Industrielle","version": 1,"formation_code": "FCOD1","type_parcours": 600,"code_specialite": "","formation_id": 1 }
formsemestre_list GET formation_id semestre_id
titre
etat
annee
date_debut
/api/formation_list?formation_id=1
formsemestre_partition_list GET semestre_id partition_id
partition_name
group_id
group_name
/api/formsemestre_partition_list?semestre_id=1
formsemestre_partition_list GET semestre_id partition_id
partition_name
group_id
group_name
/api/formsemestre_partition_list?semestre_id=1
module_list GET semestre_id module_id
module_name
/api/module_list?semestre_id=1
eval_list GET module_id evaluation_id
eval_description
/api/eval_list?module_id=1
evaluation_listenotes GET evaluation_id /api/evaluation_listenotes?evaluation_id=1312
setGroups POST partition_id
groupsLists
groupsToDelete
groupsToCreate
/api/setGroups?partition_id=1&groupsLists=452,475,854&groupsToDelete=G101,G102&groupsToCreate=Gr101,Gr102
groupsLists est une liste d'etudid à inscrire dans le groupe
setNote POST evaluation_id
etudid
note
/api/setNote?evaluation_id=1312&etudid=213&note=ABS
**(en cours de modification)** | fonction | méthode | paramètres | champs résultat | exemple | exemple résultat | | -------- | -------- | -------- | -------- | -------- | -------- | |formation_list| GET | dept (facultatif) | formation_id <br>acronyme<br>titre<br>... |/api/formation_list <br><br> /api/formation_list?dept=GEII| ` { "id": 1,"dept_id": 1,"acronyme": "BUT GEII", "titre": "BUT G\u00e9nie Electrique et Informatique Industrielle", "titre_officiel": "BUT G\u00e9nie Electrique et Informatique Industrielle","version": 1,"formation_code": "FCOD1","type_parcours": 600,"code_specialite": "","formation_id": 1 }`| | formsemestre_list | GET | formation_id | semestre_id<br>titre<br>etat<br>annee<br>date_debut | /api/formation_list?formation_id=1 | | | formsemestre_partition_list | GET | semestre_id | partition_id<br>partition_name<br>group_id<br>group_name | /api/formsemestre_partition_list?semestre_id=1 | | |formsemestre_partition_list | GET | semestre_id | partition_id<br>partition_name<br>group_id<br>group_name | /api/formsemestre_partition_list?semestre_id=1 | | |module_list | GET | semestre_id | module_id<br>module_name| /api/module_list?semestre_id=1 | | |eval_list | GET | module_id | evaluation_id<br>eval_description| /api/eval_list?module_id=1 | | |evaluation_listenotes|GET|evaluation_id||/api/evaluation_listenotes?evaluation_id=1312| | |setGroups | POST | partition_id<br>groupsLists<br>groupsToDelete<br>groupsToCreate| |/api/setGroups?partition_id=1&groupsLists=452,475,854&groupsToDelete=G101,G102&groupsToCreate=Gr101,Gr102 <br>groupsLists est une liste d'etudid à inscrire dans le groupe| | |setNote | POST | evaluation_id<br>etudid<br>note| |/api/setNote?evaluation_id=1312&etudid=213&note=ABS| |
Owner

Merci à vous deux !

J'ai l'impression qu'on peut s'épargner la colonne "champs résultat", l'exemple (commenté au besoin) est suffisant.

Dans certains cas, on va essayer d'éviter les paramètres query_string, et s'orienter vers des URL, comme /api/formsemestre_partition_list/1 (quand il y a plusieurs paramètres, quelles conventions on adopte ?)

Pour en savoir plus sur le sujet, la 1ere réponse sur SO est pas mal je trouve https://stackoverflow.com/questions/4024271/rest-api-best-practices-where-to-put-parameters

Here are a few guidelines I use when determining where to put parameters in an url:

Optional parameters tend to be easier to put in the query string.

If you want to return a 404 error when the parameter value does not correspond to an existing resource then I would tend towards a path segment parameter. e.g. /customer/232 where 232 is not a valid customer id.

If however you want to return an empty list then when the parameter is not found then I suggest using query string parameters. e.g. /contacts?name=dave

If a parameter affects an entire subtree of your URI space then use a path segment. e.g. a language parameter /en/document/foo.txt versus /document/foo.txt?language=en

I prefer unique identifiers to be in a path segment rather than a query parameter.

Merci à vous deux ! J'ai l'impression qu'on peut s'épargner la colonne "champs résultat", l'exemple (commenté au besoin) est suffisant. Dans certains cas, on va essayer d'éviter les paramètres query_string, et s'orienter vers des URL, comme `/api/formsemestre_partition_list/1` (quand il y a plusieurs paramètres, quelles conventions on adopte ?) Pour en savoir plus sur le sujet, la 1ere réponse sur SO est pas mal je trouve https://stackoverflow.com/questions/4024271/rest-api-best-practices-where-to-put-parameters > Here are a few guidelines I use when determining where to put parameters in an url: > > Optional parameters tend to be easier to put in the query string. > > If you want to return a 404 error when the parameter value does not correspond to an existing resource then I would tend towards a path segment parameter. e.g. /customer/232 where 232 is not a valid customer id. > > If however you want to return an empty list then when the parameter is not found then I suggest using query string parameters. e.g. /contacts?name=dave > > If a parameter affects an entire subtree of your URI space then use a path segment. e.g. a language parameter /en/document/foo.txt versus /document/foo.txt?language=en > > I prefer unique identifiers to be in a path segment rather than a query parameter.
Collaborator

etud_dept, etud_info Attention dans la version actuelle, un étudiant qui a changé de départment existe dans chacun des deux départements. il faudrait, soit donner la possibilité de retourner plusieurs étudiants (même pour un seul code_nip) ou décréter qu'on retourne celui qui a l'inscrition la plus tardive par exemple

sem_info il est spécifié un paramètre code_nip qui ne figure pas dans l'exemple. je suppose qu'on cherche les informations sur le semestre actuel d'un étudiant ?

+1 sur la remarque d'Emmanuel, par exemple pour les partitions, je serait plutôt partisan de

POST /api/partitions/partitionid/groups avec le nom du groupe à créer en données
DELETE /api/partitions/partitionid/groups/groupid pour supprimer un group
GET /api/partitions/partitionid/groups pour avoir la liste des groupes

J'ai vu passer des exemple ou on ajoutait dans le chemin le no de version de l api pour popuvoir changer de version d'API en conservant la compatibilité avec les clients existants

**etud_dept**, **etud_info** Attention dans la version actuelle, un étudiant qui a changé de départment existe dans chacun des deux départements. il faudrait, soit donner la possibilité de retourner plusieurs étudiants (même pour un seul code_nip) ou décréter qu'on retourne celui qui a l'inscrition la plus tardive par exemple **sem_info** il est spécifié un paramètre code_nip qui ne figure pas dans l'exemple. je suppose qu'on cherche les informations sur le semestre actuel d'un étudiant ? +1 sur la remarque d'Emmanuel, par exemple pour les partitions, je serait plutôt partisan de POST /api/partitions/*partitionid*/groups avec le nom du groupe à créer en données DELETE /api/partitions/*partitionid*/groups/*groupid* pour supprimer un group GET /api/partitions/*partitionid*/groups pour avoir la liste des groupes J'ai vu passer des exemple ou on ajoutait dans le chemin le no de version de l api pour popuvoir changer de version d'API en conservant la compatibilité avec les clients existants
Contributor

Très intéressant d'ajouter les paramètres (obligatoire) dans l'URL.
Pour fixer l'ordre, on a normalement un seul paramètre parmi :
dept_id / formation_id / semestre_id / module_id / evaluation_id
=> il n'y a donc pas vraiment d'ordre à fixer entre eux.

Cela me semble logique qu'il soit en premier.

En second obligatoire, il y a soit nip, soit etud_id, mais jamais les deux.
(D'ailleurs, est ce logique d'utiliser le etud_id en paramètre ?)

/api/etud_bul/12/12398712 pour /api/etud_bul?code_nip=12398712&id_sem=12
/api/eval_list/1 pour /api/eval_list?module_id=1
/api/etud_info/12398712 pour /api/etud_info?code_nip=12398712

Pour les autres paramètres (même obligatoire), difficile de faire une convention intuitive, non ?
/api/setNote/1312/213?note=ABS pour /api/setNote?evaluation_id=1312&etudid=213&note=ABS

Très intéressant d'ajouter les paramètres (obligatoire) dans l'URL. Pour fixer l'ordre, on a normalement un seul paramètre parmi : dept_id / formation_id / semestre_id / module_id / evaluation_id => il n'y a donc pas vraiment d'ordre à fixer entre eux. Cela me semble logique qu'il soit en premier. En second obligatoire, il y a soit nip, soit etud_id, mais jamais les deux. (D'ailleurs, est ce logique d'utiliser le etud_id en paramètre ?) `/api/etud_bul/12/12398712` pour `/api/etud_bul?code_nip=12398712&id_sem=12` `/api/eval_list/1` pour `/api/eval_list?module_id=1` `/api/etud_info/12398712` pour `/api/etud_info?code_nip=12398712` Pour les autres paramètres (même obligatoire), difficile de faire une convention intuitive, non ? `/api/setNote/1312/213?note=ABS` pour `/api/setNote?evaluation_id=1312&etudid=213&note=ABS`
Author
Contributor

Si on part sur des URL sans query string, ca veut dire qu'on ne peut appeler un étudiant QUE par son nip. On s'interdit de l'appeler par son INE ou son etud_id.

On ne peut appeler un semestre QUE par son id, pas par son étape apogée.

Je ne suis pas contre, je n'utilise pas les autres méthodes.

J'ai pris en compte vos remarques et mis les résultats escomptés. J'ai aussi rajouté le paramètre dept_id partout

Je n'ai pas encore intégré les autres requêtes de Pascal.

Si on part sur des URL sans query string, ca veut dire qu'on ne peut appeler un étudiant QUE par son nip. On s'interdit de l'appeler par son INE ou son etud_id. On ne peut appeler un semestre QUE par son id, pas par son étape apogée. Je ne suis pas contre, je n'utilise pas les autres méthodes. J'ai pris en compte vos remarques et mis les résultats escomptés. J'ai aussi rajouté le paramètre dept_id partout Je n'ai pas encore intégré les autres requêtes de Pascal.
Owner

Comme tous les objets manipulés par l'application, un étudiant a toujours un id, nommé à l'extérieur etudid. Mais il n'a pas toujours un NIP ou un INE.

Sauf indication contraire, les id à utiliser sont donc ceux de scodoc (etudid, etc), pas le NIP ni l'INE.

La démarche devrait probablement être:

  1. récupérer l'etudid, via une liste d'étudiant d'un groupe ou via une interrogation directe genre get_etud_dept (qui pourrait fournir les départements et ids). Cette (ou ces) requêtes pourraient effectuer des recherches par NIP, INE, nom, étape, ...

  2. Utiliser l'etudid obtenu pour récupérer d'autres éléments (bulletins, absences, ....) ou manipuler l'étudiant (incriptions, ajout absences, ...).

Comme tous les objets manipulés par l'application, un étudiant a toujours un id, nommé à l'extérieur etudid. Mais il n'a pas toujours un NIP ou un INE. Sauf indication contraire, les id à utiliser sont donc ceux de scodoc (etudid, etc), pas le NIP ni l'INE. La démarche devrait probablement être: 1. récupérer l'etudid, via une liste d'étudiant d'un groupe ou via une interrogation directe genre get_etud_dept (qui pourrait fournir les départements et ids). Cette (ou ces) requêtes pourraient effectuer des recherches par NIP, INE, nom, étape, ... 2. Utiliser l'etudid obtenu pour récupérer d'autres éléments (bulletins, absences, ....) ou manipuler l'étudiant (incriptions, ajout absences, ...).
Collaborator

+1 (et ça évite de se trimballer un departement en plus - car l etudid lui est unique sur tous les depts)

+1 (et ça évite de se trimballer un departement en plus - car l etudid lui est unique sur tous les depts)
Author
Contributor

J'ai mis à jour. Mais comment etud_dept peut-il recevoir soit un NIP soit un INE soit un nom ? Il cherchera ce qu'on a mis dans code_nip dans tous les champs de la BDD ?

J'ai mis à jour. Mais comment etud_dept peut-il recevoir soit un NIP soit un INE soit un nom ? Il cherchera ce qu'on a mis dans code_nip dans tous les champs de la BDD ?
Contributor

Ca complique peut être , mais pour etud_dept, peut-on envisager :
/api/etud_dept/123 : recherche par nip
/api/etud_dept/ine/123456789 : recherche par ine
/api/etud_dept/nom/dupont : recherche par nom ( plusieurs réponses possibles)

Ca complique peut être , mais pour etud_dept, peut-on envisager : /api/etud_dept/123 : recherche par nip /api/etud_dept/ine/123456789 : recherche par ine /api/etud_dept/nom/dupont : recherche par nom ( plusieurs réponses possibles)
Owner

Et pour récupérer la photo d'un étudiant ce serait:

/api/photo/<etudid>

ou pour la version réduite:

/api/photo/<etudid>/small
Et pour récupérer la photo d'un étudiant ce serait: ``` /api/photo/<etudid> ``` ou pour la version réduite: ``` /api/photo/<etudid>/small ```
Author
Contributor

Ok j'ai mis à jour, j'ai donc supprimé photo_url de etud_info

Ok j'ai mis à jour, j'ai donc supprimé photo_url de etud_info
Contributor

Bonjour à tous,

Suite à la réunion, voici les fonctions que j'utilise et qui ne sont pas prévus dans l'API (à moins qu'ils soient prévus avec un autre nom que je n'ai pas saisi) :

  • get_etud_dept (mais vous en avez parlé dans les commentaires),
  • groups_view pour lister tous les étudiants d'un semestre,
  • formsemestre_description pour lister les UE et les modules d'un département,
  • list_depts pour avoir la liste des départements disponibles.

A bientôt,
Seb

Bonjour à tous, Suite à la réunion, voici les fonctions que j'utilise et qui ne sont pas prévus dans l'API (à moins qu'ils soient prévus avec un autre nom que je n'ai pas saisi) : * get_etud_dept (mais vous en avez parlé dans les commentaires), * groups_view pour lister tous les étudiants d'un semestre, * formsemestre_description pour lister les UE et les modules d'un département, * list_depts pour avoir la liste des départements disponibles. A bientôt, Seb
Owner

Bonjour à tous,

Suite à la réunion, voici les fonctions que j'utilise et qui ne sont pas prévus dans l'API (à moins qu'ils soient prévus avec un autre nom que je n'ai pas saisi) :

  • get_etud_dept (mais vous en avez parlé dans les commentaires),

est actuellement acessible à tous

  • groups_view pour lister tous les étudiants d'un semestre,

groups_view n'est pas actuellement accessible en mode "scodoc7" dans ScoDoc9. Sera dans l'API, probablement sous un autre nom.

  • formsemestre_description pour lister les UE et les modules d'un département,

idem

  • list_depts pour avoir la liste des départements disponibles.

idem

(si besoin urgent de ces fonctions en ScoDoc 9.0, me dire, on peut les rebrancher en attendant l'API)

> Bonjour à tous, > > Suite à la réunion, voici les fonctions que j'utilise et qui ne sont pas prévus dans l'API (à moins qu'ils soient prévus avec un autre nom que je n'ai pas saisi) : > > * get_etud_dept (mais vous en avez parlé dans les commentaires), est actuellement acessible à tous > * groups_view pour lister tous les étudiants d'un semestre, groups_view n'est pas actuellement accessible en mode "scodoc7" dans ScoDoc9. Sera dans l'API, probablement sous un autre nom. > * formsemestre_description pour lister les UE et les modules d'un département, idem > * list_depts pour avoir la liste des départements disponibles. idem (si besoin urgent de ces fonctions en ScoDoc 9.0, me dire, on peut les rebrancher en attendant l'API)
Owner

#d2f41b6a21 avance un peu sur le sujet.

#d2f41b6a21 avance un peu sur le sujet.
Contributor

Oui tu m'avais déjà dit pour ces fonctions non accessibles, mais j'ai tout de même trouvé un moyen d'y accéder sur Scodoc 9 en utilisant une petite faille non critique du système :

  • je m'authentifie avec une première requête valide en utilisant CURL,
  • je conserve le cookie de retour dans un cookie jar,
  • j'envoie les autres requêtes avec ce cookie, et ça passe même si ce n'est pas exposé sur l'API.

Du coup j'ai accès à tout ce qu'il me faut.

Code exemple : https://github.com/SebL68/Scodoc_Notes/blob/main/includes/serverIO.php

Le problème risque de venir avec la nouvelle API, c'est pourquoi je parle tout de suite des besoins qui ne sont pas encore listé, pour ne pas les oublier.

Oui tu m'avais déjà dit pour ces fonctions non accessibles, mais j'ai tout de même trouvé un moyen d'y accéder sur Scodoc 9 en utilisant une petite faille non critique du système : * je m'authentifie avec une première requête valide en utilisant CURL, * je conserve le cookie de retour dans un cookie jar, * j'envoie les autres requêtes avec ce cookie, et ça passe même si ce n'est pas exposé sur l'API. Du coup j'ai accès à tout ce qu'il me faut. Code exemple : https://github.com/SebL68/Scodoc_Notes/blob/main/includes/serverIO.php Le problème risque de venir avec la nouvelle API, c'est pourquoi je parle tout de suite des besoins qui ne sont pas encore listé, pour ne pas les oublier.
Owner
Voir https://docs.google.com/spreadsheets/d/1k6VtENWuZRLyssjvmzE7_FZpB_VpJ4xrNdN_M_fWCXU/edit?usp=sharing
Sign in to join this conversation.
No Milestone
No project
No Assignees
5 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: ScoDoc/ScoDoc#149
No description provided.