Les WebService RESTful (REST API)

Un web-service RESTful (aussi appelé REST-API) permet de mettre à disposition, pour d’autres applications, des ressources (que ce soit des fichiers, des  données issues d’une base de données, d’un autre web-service, etc…).
La mise en place et l’utilisation d’un service RESTful est donc beaucoup plus simple que SOAP, ou son ancêtre XML-RPC, qui ajoutent eux une sur-couche au protocole HTTP mais permettent en revanche d’exposer des fonctionnalités (tel que des fonctions de calcul par exemple), ce que ne permet pas (à priori) RESTful.

RESTful est donc fortement recommandé pour des cas simples où on cherche à effectuer des actions sur un contenu, comme lister des ressources, accéder à une ressource en particulier, en créer de nouvelles, modifier une ressource existante, ou en supprimer une.

Exemple d’utilisation

Un web-service RESTful a pour but d’être interrogé par une autre application, que cette dernière soit un site (via Javascript AJAX), une application desktop, ou encore une application pour mobile…
Par exemple, une application mobile peut utiliser un webservice RESTful afin de récupérer la liste des produits à afficher en son sein, puis les détails de chaque produit (descriptions, prix, chemin des images, disponibilité…) pour les afficher sur une « page » prévu à cet effet.

Les échanges de données se limitant généralement à du texte brute cela est rapide et efficace.

Protocole

L’architecture RESTful repose sur le protocole HTTP.

Comme expliqué par Gérald Croes dans son blog : On accède à une ressource par son URI unique, pour procéder à diverses opérations supportées par HTTP : les verbs/method HTTP.
On peut demander à :

  1. Lire une ressource, ou une collection de ressources (GET)
  2. Modifier une ressource existante (PUT)
  3. Créer une ressource (POST)
  4. Supprimer une ressource (DELETE)

Une API RESTful est donc un système CRUD pour Create / Read / Update / Delete.

Noter qu’il est aussi possible d’utiliser le verbs HTTP HEAD afin, par exemple, de récupérer les informations (dimensions, poids, mime-type, etc..) sur une image existante.

Exemple

  • Un GET http://www.example.com/customers signifie que je souhaite récupérer la liste des clients disponibles.
  • En revanche une GET http://www.example.com/customers/2 signifie que je souhaite récupérer les informations du client dont l’identifiant est 2.
  • Au même titre, un DELETE http://www.example.com/customers/2 devrait supprimer le client #2

Mise en place avec PHP

  1. Ressource et action : La propriété $_SERVER[‘REQUEST_URI’] vous permet de récupérer L’URI demandé (attention à la parser si vous n’êtes pas à la racine de votre serveur).La propriété $_SERVER[‘REQUEST_METHOD’] vous permet de récupérer le verbs/method HTTP d’appel de votre script.
    Ces deux propriétés vous permettent donc de savoir quelle action exécuter sur quelle ressource.
  2. Les données posté pour ajout ou modification : Les données pour l’ajout d’une ressource étant transmise par un POST, elles sont très facilement récupérables dans la super-globale PHP $_POST.Ce n’est malheureusement pas aussi simple pour la modification avec le verbs/method PUT.En effet ce dernier n’a pas de super-globale $_PUT, et les données ne sont pas non plus présentes dans $_POST.
    Mais nous pouvons récupérer les data au format brut en lisant l’entrée (input) de PHP : file_get_contents(« php://input »);
    Il nous faudra alors parser manuellement les données (qui peuvent être au format URL, JSONou encore XML).
  3. Exécuter les actions adéquates : Une fois que nous avons la ressource cible, l’action a effectuer (verbs HTTP), il ne nous restera plus qu’a exécuter la dite action sur la ressource.Par exemple pour GET http://www.example.com/customers, qui a pour but de lister les clients, il nous faudra :
    • Nous connecter à la base de données.
    • Effectuer un SELECT sur la table correspondante aux ressources demandées.
    • Récupérer les enregistrements pour les transformer en JSON (par exemple, mais cela pourrait aussi être de l’XML, nombre d’API RESTful sont d’ailleurs paramétrable sur le format de sortie grâce à un paramtètre d’URL).
    • Et enfin les renvoyer à l’affichage pour que le client puisse les charger.
  4. Filtrer les résultats : Lors qu’une requête GET (dont le but et de récupérer une liste d’entité), il est possible d’effectué un tri, afin de filtrer les résultats.
    Ceci ce fait via les paramètres GET de l’URL.
    Par exemple, pour récupérer la liste des client ayant dépensé plus de 100€ dans mon magasin, l’on peut imaginer une URI tel que : GET http://www.exemple.com/customers?total=100, faudra alors modifier la requête SQL en fonction de ce paramètre.
  5. Gestion des erreurs : Une API RESTful se doit de respecter les normes HTTP, elle doit donc répondre les bons statuts HTTP en fonction du résultat de la requête.Par exemple, une ressource non trouvé se doit d’avoir, en plus du message d’erreur que vous pouvez faire remonter dans le corps du message, une entête HTTP avec un statut 404 Not Found.De même, si votre API est protégée par un accès sécurisé, toute requête non autorisée devra renvoyer un statut 403…

Rappels

L’architecture REST utilise les spécifications originelles du protocole HTTP, plutôt que de réinventer une surcouche (comme le font SOAP ou, son ancêtre, XML-RPC par exemple).

    1. L’URI comme identifiant des ressources.
    2. Les verbes HTTP comme identifiant des opérations.
    3. Les réponses HTTP comme représentation des ressources (HTML, XML, CSV, JSON, …).

Optionnel:

  1. Des liens comme relation entre ressources.
  2. Un paramètre dans entête comme jeton d’authentification.

Plus d’infos…

Wikipedia : http://fr.wikipedia.org/wiki/Representational_State_Transfer
Gerald’s Blog : http://www.croes.org/gerald/blog/qu-est-ce-que-rest/447/
Slides de David Züelke au Symfony Live 2012 Paris : http://goo.gl/Gc5nD
Site du W3C sur les entêtes HTTP : http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

Une réflexion au sujet de « Les WebService RESTful (REST API) »

  1. strange

    Très intéressant. Il faudrait que j m mettes au dev un jour… Mais continue cela est pour moi très instructif déjà. Merci pour le travail.

    Répondre

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *