API REST : Vue d'ensemble
Le serveur Regovar expose une API Rest via aioHTTP. Tout le code concernant l'API se trouve dans le répertoire /regovar/web
. L'API permet d'accéder et de gérer les resources de Regovar ainsi que de réaliser toutes les fonctionnalités proposées par le serveur via une interface web.
Pour connaître les détails concernant les resources et fonctionnalités de Regovar, lire la section concernant le core
Principaux points d'entrée
Les points d'entrée principaux de l'API sont les suivants :
/users
: pour la manipulation des utilisateurs de Regovar/projects
: pour la manipulation des projets de Regovar- ... à venir ...
Règles générales
CRUD
POST Create
GET Read
PUT Update
DELETE Delete
Réponses et prise en charge des erreurs
Les seuls codes d'erreur HTTP retournés par le server sont :
Code | Description |
---|---|
200 |
"OK", le server fonctionne bien et vous a répondu (ce qui ne veut pas dire qu'il n'y a pas eu d'erreur) |
404 |
"request not found", l'url saisie n'existe pas |
403 |
"authentication required", l'utilisateur doit être identifié pour accéder au service, ou bien l'authentification a échoué (mauvais login/mot de passe saisis) |
5XX |
"server errors", une erreur non gérée côté server est survenue et a "cassé" le server... ça craint. |
Donc en théorie, quand tout fonctionne normalement, le server doit toujours renvoyer du JSON (utf8), avec code HTTP valant 200
.
La structure de la réponse JSON est toujours la même :
En cas de succès du traitement de la requête
HTTP code = 200
{
"success" : True, // boolean à vrai pour indiquer le traitement avec succès
// Optionnel si resultat attendu
"data" : json, // toujours formaté en JSON
// Optionnel si pagination du resultat
"range_offset" : int, // l'offset de départ des résultats
"range_limit" : int, // la limit autorisée du nombre de résultats renvoyés utilisé par la requête (1000 par défaut)
"range_total" : int, // le nombre total d'éléments en base de donnée (à e pas confondre avec le nombre d'élement retournée par la requête)
}
En cas d'erreur (gérée) lors du traitement de la requête
HTTP code = 200
{
"success" : False, // boolean à faux
"msg": string, // un message d'erreur humainement compréhensible en anglais
"error_code": string, // le code d'erreur
"error_url": string, // l'url de la doc en ligne concernant l'erreur
"error_id": string // l'identifiant unique de l'erreur qui permet de localiser facilement l'erreur dans les logs.
}
Lazy Loading
Par défaut une requête va retourner les ressources avec un certain nombre de champs renseignés. Pour économiser de la bande passante il est parfois nécessaire de ne récupérer que les infos dont on a besoin. Par défaut les requêtes qui renvoient des listes de résultat ne fournissent qu'un nombre limité d'information, alors que les requêtes qui retournent un seul résultat vont retourner l'ensemble des infos disponibles. Mais tout ceci est détaillé dans les pages dédiées aux points d'accès des différentes ressources.
Pour les requêtes qui supportent le lazy loading (par exemple /users
qui retourne la liste des utilisateurs), il est possible de spécifier quels champs à retourner dans la réponse.
Query Parameter : ?fields={fieldname}[,{fieldname2},...]
Exemple :
GET regovar.org/users
{
"success" : True,
"data": [{
"id" : int;
"firstname": string,
"lastname" : string,
"function" : string,
"location" : string,
"email" : string,
"roles" : json,
// ...
}]
}
GET regovar.org/users?fields=id,email
{
"success" : True,
"data": [
{"id" : 1, "email" : "user1@mail.com"},
{"id" : 2, "email" : "user2@mail.com"},
{"id" : 3, "email" : "user3@mail.com"},
...]
}
Pagination
Pour les requêtes qui la supportent (par exemple /users
), il est possible de spécifier la plage de résultat à retourner.
Query Parameter : ?range={first}-{end}
- Retourne la liste des résultat allant du
{first}
au{end}
inclus (à noter que le premier élément à pour index 0).
Exemple :
GET regovar.org/alphabet
{
"success" : True,
"data": ["a", "b", ... "z"] // total = 26 éléments
}
GET regovar.org/alphabet?range=2-6
{
"success" : True,
"data": ["c", "d", "e", "f"],
"range_offset" : 2,
"range_limit" : 4, // = min ({end}-{first}, Default_limite=1000)
"range_total" : 26
}
Filtrage
Pour les requêtes qui le supportent (par exemple /users
), il est possible de spécifier des paramètres de filtrage pour ne retourner qu'une certaine partie des résultats.
Query Parameter : ?{fieldname}={value}[,{or_value},...][&{fieldname2...}]
- On peut filtrer en précisant en paramètre un champs de la ressource et la valeur attendue. La liste des champs filtrables est fournie par la requête principale sans aucun argument (dans notre exemple la requête
/users
). Seuls les attributs directs de la ressource peuvent être filtrés.; - On peut filtrer sur plusieurs champs à la fois en les séparant avec le
&
. Dans ce cas le moteur de filtrage appliquera implicement la conditionAND
entre chaque champs filtré; - On peut filtrer sur plusieurs valeurs pour un même champs, en les séparant avec le symble
,
. Pour le moteur de filtrage il s'agira d'appliquer unOR
pour chacune de ces valeurs; - il n'est pas possible de faire du filtrage complexe via ce systeme. Ainsi pour les recherches ou filtrages nécessitant l'usage d'expression régulière, d'opérateur type
>=
, etc, si la ressource le permet, une requete dédiée sera proposée (par exemplePOST
/users/search
).
Exemple :
GET regovar.org/users?firstname=Toto
// Return list of user with firstname == "Toto"
{
"success" : True,
"data": [
{
"id" : 15,
"firstname" : "Toto",
"lastname" : "TOTO",
},
{
"id" : 16,
"firstname" : "Toto",
"lastname" : "TATA",
}]
}
GET regovar.org/users?firstname=Toto,Titi&lastname=TATA
// Return list of user with (firstname == "Toto" or "Titi") and with lastname == "TATA"
{
"success" : True,
"data": [
{
"id" : 16,
"firstname" : "Toto",
"lastname" : "TATA",
}]
}
Ordonner
Pour les requêtes qui le supportent (par exemple /users
), il est possible de spécifier des paramètres pour ordonner les résultats selon certains champs par ordre croissant ou décroissant.
Query Parameter : ?sort={field1}[,{field2},...][&desc={fieldX}[,{fieldY}]]
- L'attribut
sort
permet de lister les champs dans l'ordre suivant lequel les résultats vont être ordonnés (par ordre croissant pour chaque champs); - L'attribut
desc
liste les champs (parmis ceux avec l'attributs sort qui doivent suivrent l'ordre décroissant et non croissant)
Exemple :
GET regovar.org/users?sort=lastname,firstname
// Retourne la liste des utilisateur par ordre alphabétique des Nom, puis des Prénoms
GET regovar.org/users?sort=lastname,firstname&desc=lastname
// Retourne la liste des utilisateur par ordre alphabétique inversé des Nom, puis par ordre alphabétique des Prénoms
Search
... à définir ...
Identification et authentification
Qui dit internet, dit authentification des utilisateurs à distance, session et mot de passe. Tout cela est géré via le point d'entrée /users
, grâce aux actions :
POST
/users/login
: qui permet l'authentification grâce aux paramètreslogin
etpassword
à fournir dans le corps de la requête. Si l'authentification échoue, une erreur 403 est retournée (Forbidden); si elle réussit,GET
/users/logout
: