SPORE, Specifications for a POrtable Rest Environnement
- François
Combien d’API Rest appelez-vous ? Combien de temps passez-vous à chercher une bonne librairie pour interroger votre API préférée ?
Frank Cuny a présenté SPORE, lors de l’édition 2010 d’OSDC.fr, une spécification pour décrire simplement en JSON une API Rest.
Le fichier de description est plutôt simple : une partie qui décrit l’API en général et une liste de méthodes. Seules quelques informations sont obligatoires. On va retrouver comme informations :
- l’URL de base de l’api : base_url
- l’URI pour la méthode : path
- le verbe HTTP : method
- des paramètres obligatoires ou optionnels : required_params et optional_params
- des entêtes HTTP : headers
- et quelques autres possibilités : deprecated, unattended_params, expected_status…
Voici un exemple de description de l’API de github :
SPORE ne s’arrête pas seulement à décrire une API, mais a pour but également de normaliser les clients qui implémentent SPORE. En normalisant l’API du client on évite de se retrouver bloqué en ne pouvant utiliser les dernières fonctionnalités de l’API.
Ainsi un client SPORE propose de créer un client à partir d’un fichier de description. Dans le cas d’une API conséquente avec plusieurs dizaines de méthodes, il est possible de créer un client avec plusieurs fichiers.
Le point le plus important de SPORE est la définition des middlewares. Les middlewares sont des petits bouts de code qui ont pour but de s’intercaler à différents moments de l’exécution du client. Dans SPORE on peut s’intercaler avant la requête au serveur et après avoir reçu la réponse. SPORE décrit l’environnement minimal accessible dans les middlewares.
Un middleware sur la requête peut changer à la volée des paramètres, en rajouter, gérer l’authentification ou bien encore court-circuiter la requête en renvoyant directement la réponse (pour du mock dans les tests ou du cache). Un middleware sur la réponse peut lui aussi modifier la réponse ou même renvoyer sa propre réponse !
Les middlewares sont appelés les uns après les autres. Petite subtilité, les middlewares de réponse sont appelés dans l’ordre inverse des middlewares de requêtes.
Avec les middlewares vous gérez la logique spécifique de l’API : l’authentification, la dé-sérialisation du contenu, etc.
SPORE a des implémentations fonctionnelles dans différents langages :
Lors du jsmeetup 2, j’ai présenté SPORE et l’implémentation nodejs. Voici un petit exemple :
// création du client
var client = spore.createClient(__dirname +'/github.json');
// récupération des informations d'un utilisateur github
// le methode get_info a été créé automatiquement
client.get_info({format: 'json', 'username': 'francois2metz'}, function(err, msg) {
if (err) throw err;
console.log(msg);
});
La méthode get_info étant accessible sans authentification, on n’a pas de problèmes pour récupérer les informations.
Si on veut récupérer les informations du profil d’un utilisateur, il faut s’authentifier. GitHub passant à OAuth2, on peut utiliser le middleware OAuth2 fourni dans node-spore.
// création du client
var client = spore.createClient(__dirname +'/github.json');
// vous devez avoir récupéré un token auparavant
var oauth2 = require('spore/middlewares').oauth2(access_token);
client.enable(oauth2)
client.get_profile({format: 'json'}, function(err, msg) {
if (err) throw err;
console.log(msg);
});
Plutôt simple non ?
Si vous voulez en savoir plus, voici quelques liens :
Have a comment? Contact me by email.