Dans ce petit billet, nous allons tâcher de présenter simplement ce que sont les services web REST et le format d’échange JSON.
L’architecture REST
Commençons par le commencement. Une piqure de rappel sur le protocole HTTP n’est jamais malvenue.
Pour faire simple, une requête HTTP se présente ainsi :
- Une méthode (GET, POST, PUT, DELETE)
- Un chemin vers une ressource (/index.php, /liste/contenu/)
- Une version du protocole (1.0 ou 1.1 généralement)
- Un ensemble de propriétés et valeurs (Content-Type, Length)
- Un contenu (facultatif)
C’est autour de ce protocole que s’organise l’architecture REST.
Les méthodes HTTP sont donc utilisées ainsi :
- GET : lecture d’information
- POST : envoi d’information
- PUT : mise à jour d’information
- DELETE : suppression d’information
Par exemple, si je veux lire la liste des adhérents à mon club d’échecs, j’effectue une requête de type GET vers la ressource http://monsite.com/adherents . Si je veux les adhérents ayant plus de 20 ans, je peux faire http://monsite.com/adherents?ageMinimum=20.
De la même manière, si je veux supprimer les adhérents 3 et 4, je peux faire une requête de type DELETE vers http://monsite.com/adherents/3/4.
Si on veut envoyer des informations, on utilise POST ou PUT en passant les informations dans le corps du message.
REST du côté serveur
La plupart d’entre vous utilisent PHP pour interpréter les informations du côté du serveur. Nous allons donc nous baser sur ce langage afin d’expliquer le fonctionnement.
Tout d’abord, il faut savoir quelle est la méthode utilisée. Et là, premier problème : PHP ne semble gérer que les requêtes de type POST et GET, qui sont utilisées par HTML.
Récupérons d’abord la méthode HTTP
Pour cela, il suffit d’utiliser les données du serveur.
// $method sera égal à 'get', 'post', 'put' ou 'delete' $method = strtolower($_SERVER['REQUEST_METHOD']);
Pas de soucis pour GET et POST
Les méthodes GET et POST ne posent pas de soucis particulier : leur contenu est passé respectivement dans les tableaux $_GET et $_POST.
Pas de soucis non plus pour DELETE
La méthode DELETE envoie ses paramètres dans l’URL ( accessible via $_SERVER['REQUEST_URI'])
Il reste les paramètres de PUT
La méthode PUT envoie elle des informations dans le corps du message. Comment les récupérer en PHP ?
Voici la solution :
// récupération des données brutes $raw_data = file_get_contents('php://input'); // transformation en tableau à indexes ($put_data) parse_str($raw_data, $put_data);
Format des échanges : JSON
Les données échangées doivent pouvoir être comprises par le côté serveur comme le côté client.
Pour cela, un format simple avec une forte capacité de compression a fait son apparition : JSON.
JSON s’architecture autour du format des objets ECMAScript (JavaScript) .
Les 2 principales caractéristiques sont :
- Le principe de clé / valeur
- L’organisation des données sous forme de tableau
Les types de données valables sont :
- tableau
- objet
- chaîne de caractères
- valeur numérique (entier, double)
- booléen (true/false)
- null
Par exemple, pour récupérer le nom, le prénom et l’âge d’une personne dans un objet :
{ "nom": "xxxx", "prenom": "yyyy", "age": 25 }
Une liste d’articles :
[ { "nom": "article a", "prix": 3.05, "disponible": false, "descriptif": "mon article a ..." }, { "nom": "article b", "prix": 13.05, "disponible": true, "descriptif": null } ]
Vous trouverez plus d’informations sur le format JSON au travers du site officiel : http://www.json.org/json-fr.html
Pour les données binaires (images et autres), il suffit de donner une adresse en lecture et une propriété en écriture.
Par exemple, si je veux envoyer une image avec un descriptif, mes variables POST seront organisées ainsi :
- json : descriptif au format json
- image : image au format binaire
La lecture des données au niveau serveur se fait ainsi :
$result = json_decode($json_data);
L’écriture, basée sur un tableau à indexes, se fait ainsi :
$json_str = json_encode($data_array);
Vous trouverez toutes les informations nécessaires sur http://www.php.net/manual/fr/ref.json.php.
Pour finir, le type de données utilisé généralement pour décrire un contenu JSON est application/json.
Avec ceci, vous avez de quoi réaliser des services web performants et simples à mettre en oeuvre !
