Principe général¶
Les webservices sont utilisables via une API web en effectuant des requêtes sur le module /wsapi/.
Ils sont définis sur un modèle REST (stateless => pas de session).
Différentes actions peuvent être proposées en fonction du chemin de l'URL.
Les chemins devraient respecter une logique /"type"/"commande".
La partie "commande" est facultative, chaque "type" pouvant disposer d'une "commande" par défaut.
Permissions¶
Les webservices sont soumis aux mêmes règles d'accès que l'application classique avec son système de permissions.
Une authentification peut être effectuée à chaque requête sur l'API web, basée sur les usagers de l'application :
l'utiliser revient exactement au même que se connecter sur l'application avec son compte
(identifiant et mot de passe du compte usager, application du profil et des permissions).
L'authentification est facultative, ce qui à défaut revient à consulter l'application sans avoir de compte.
Note : La majorité des requêtes ne feront que retourner des données publiques pour lesquelles un accès anonyme sera suffisant.
Ainsi l'authentification ne sera utile que pour quelques commandes récupérant des informations personnelles
(informations sur son compte, liste des sessions incluant ses sessions libres non publiques...)
ou éventuellement des commandes devant effectuer des actions privilégiées (accès à des données masquées, mise à jour de données...).
Authentification¶
L'authentification repose sur les mécanismes standards fournis par le protocole HTTP avec la méthode "BASIC".
Pour info la méthode "DIGEST" qui permet l'authentification sans faire transiter le mot de passe sur le réseau
n'est pas envisageable car elle nécessite en contre partie que le serveur puisse connaitre les mots de passe.
Or par sécurité les mots de passe ne sont pas stockés en clair et le chiffrement utilisé est non-bijectif.
Enfin si la méthode "BASIC" transmet le mot de passe, cela n'est pas génant à condition de bien utiliser HTTPS
pour chiffrer la communication.
Requêtes¶
Les commandes actuellement en place sur l'API web sont les suivantes :
- Liste des EPN : /wsapi/epn/list ( ou juste /wsapi/epn )
- Liste des Sessions : /wsapi/session/list ( ou juste /wsapi/session )
- Infos de l'usager : /wsapi/user/info ( ou juste /wsapi/user )
La dernière requête nécessite donc une authentification pour retourner le profil du l'usager authentifié.
Pour la seconde requête, seule la liste des sessions publiques sera retournée à défaut d'authentification.
La première requête quant à elle n'a aucun besoin d'authentification, les données transmises sont publiques.
Réponses¶
Toutes les commandes de l'API web fournissent des réponses similaires :
- Content-type "application/json" avec encodage UTF-8
- Contenu textuel représentant un objet au format JSON
- L'objet contient toujours un premier champs "status" indiquant "OK" ou "ERROR"
- L'ensemble des résultats (ou le message d'erreur) se trouve dans le second champs "data"