★ Pour ne plus être en REST, comprendre cette architecture

Depuis quelques mois, j'apprends j'essaye d'apprendre REST et j'ai lu de nombreuses pages sans pour autant trouver d'explication simple, à la portée de tous. Du coup quand j'essaye d'expliquer les mécanismes et les avantages professionnellement, c'est pas toujours convaincant... et je voulais justement écrire un petit billet pour mettre tout ça au clair. Et puis je suis récemment tombé sur une série d'explications par Softies on Rails se basant sur des exemples concrets. En voici la traduction chronologique.

Comprendre les ressources

D'une certaine manière, apprendre REST fut très difficile pour moi. Je ne sais pas vraiment pourquoi. Peut-être car j'ai passé une bonne partie de ma vie à développer des applications client et non des applications web. Peut-être est-ce parce que (à lire rapidement) j'ai commencé à développer pour le web tout en apprenant Ruby tout en apprenant Rails et que j'ai ensuite été à RailsConf et tout le monde était excité par REST et j'approuvais pour ne pas passer pour un imbécile mais honnêtement je ne savais pas de quoi il retournait...

Si vous essayez de comprendre REST, cette série est faite pour vous.

Les experts en HTTP, HTML et REST pourraient chercher la petite bête avec ma terminologie simplifiée me permettant d'aller droit au but. Si c'est votre cas, je ne veux pas en entendre parler, car cette série ne vous est pas destinée de toute façon :-)

Premier point

Commençons par le commencement. Comment fonctionne un navigateur ? Avant d'essayer de développer des sites avec Rails, je pensais que ça marchait ainsi :

• je tape une url dans la barre d'adresse ou je clic sur un lien ;
• le navigateur fait une « requête http » (quoi que cela puisse signifier) et obtient du code HTML en réponse ;
• le navigateur interprète ce HTML pour afficher la page.

Et c'est à peu près tout. Et je ne me suis jamais demandé comment les formulaires fonctionnaient. Je me disais juste que ça devait être une variante de la précédente description.

En réalité, le protocole HTTP décrit les instructions détaillées de la façon dont un navigateur doit envoyer ses requêtes au serveur. HTTP est totalement différent du HTML, qui est le langage choisit pour représenter le contenu d'une page. HTTP permet au navigateur de récupérer divers types d'informations à partir du serveur, dont la simple récupération d'une page HTML ou la soumission d'un formulaire. En fait, HTTP permet d'effectuer huit types de requêtes différentes sur le serveur. Les deux requêtes les plus connues sont les suivantes :

• une requête « GET » : récupère le contenu d'une ressource sur le web, la ressource est uniquement identifié par une URL ;
• une requête « POST » : envoie des données à une URL afin de créer une nouvelle ressource.

Deuxième point

Remarquez comme j'ai glissé le mot « ressource » alors que vous ne l'attendiez pas. Ça a été mon premier mal de tête lorsque j'ai essayé de comprendre REST : penser au web comme un ensemble de ressources, pas de « pages web ». Qu'est-ce que je veux dire par là ?

Hier, je suis allé sur amazon.com et j'ai consulter quelques produit que je voudrais acheter. J'ai aussi lu quelques articles de Wikipedia. J'ai parcouru quelques news de TechCrunch et j'ai ensuite vérifier les scores de D1 pour constater à quel point Lyon est loin devant.

Si vous voulez comprendre REST, vous devez arrêter de penser à tout ça en termes de pages web. Prenons l'exemple d'un article de Wikipedia. Ce n'est pas seulement une page web, c'est une ressource - dans notre exemple un biographie d'Archimède. J'utilise un navigateur web pour accéder à cette ressource, le navigateur récupère donc une représentation HTML de cette ressource, car afficher du HTML est la seule possibilité de représentation de ces ressources par un navigateur.

Je sais que c'est étrange au début. L'article sur Archimède n'est pas une page web ? Non. J'ai demandé la représentation HTML d'une ressource appartenant à Wikipedia, une ressource pouvant être identifiée par l'URI « //fr.wikipedia.org/wiki/Archimède ». Wikipedia aurait pu choisir de représenter cette ressource de beaucoup de façons - avec un PDF, ou peut-être une image .jpg. C'est même peut-être déjà possible. Mais Firefox utilise une requête GET qui spécifie que cette ressource doit être obtenue à partir du serveur sous forme de HTML, donc c'est ce que j'ai.

Un autre exemple : ma réservation d'avion est une ressource détenue par Air France. Ils me permettent d'accéder à cette ressource de diverses manières : via une page HTML, mais ils peuvent aussi envoyer les informations de ma réservation sur mon téléphone portable. Ou ils peuvent me l'envoyer par mail en texte brut. Ou je peux les appeler avec un outil obsolète et ils vont me le dire de vive voix. Une même ressource, plusieurs représentations.

J'espère que c'est clair maintenant : ma réservation d'avion n'est pas qu'une page web. C'est une vraie ressource qui (heureusement pour moi) peut être affichée en HTML lorsque je le désire, et je peux utilise mon navigateur pour demander cette représentation et l'afficher sur mon écran.

Troisième point

Ok, maintenant que vous avez accepté le fait que le web est une gigantesque collection de ressources qui peuvent être servies de différentes manières, et qu'un affichage HTML est juste l'une d'entre elles, il y a maintenant un dernier concept que je souhaite aborder. Les ressources ne sont pas uniquement des simples articles biographiques, ou des réservations d'avions, ou des résultats sportifs. Certaines ressources sont des collections d'autres ressources. Une liste de vacances peut être une ressource. Une liste d'amis peut être une ressource. Une série de billets de blog peut être une ressource.

Maintenant que vous avez compris ce que sont les ressources, nous allons maintenant nous intéresser à la façon dont HTTP permet la création, la récupération, la mise à jour et la suppression des ressources (NdT : bon normalement c'est crud pour create, retrieve, update et delete).

Des millions d'API

Analyse orientée objet et design

Si vous programmez en orienté objet depuis un certain temps, vous avez probablement appris à procéder de la façon suivante :

• écrire une description de votre problématique - ce que votre programme est censé faire.
• les noms sont vos classes.
• les verbes sont les méthodes de vos classes.
• permettre à vos noms d'appeler les méthodes d'autres noms pour qu'ils accomplissent des tâches.

Ça semble bon. C'est ce que je fais en programmation depuis un moment déjà. Ce type de programmation par nom-verbe est souvent appelé style RPC. Je ne sais pas en quoi c'est proche de l'accès à distance mais je sais juste que le style RPC est la façon « classique » de développer des logiciels avec de l'orienté objet. C'est une très bonne manière pour développer des logiciels mais ce n'est pas la façon dont le web a été pensé. Pourquoi ça ?

Imaginez-vous en 1992 (ou juste avant que le web soit tel que vous le connaissez aujourd'hui). Et supposez 3 équipes différentes qui développent 3 logiciels : un pour acheter des livres, un pour acheter des billets d'avion et un autre qui permet d'obtenir des photographies aériennes de n'importe quelle distance de la Terre. Elles suivent toutes les 3 les techniques de modélisation orientée objet classiques dont nous avons parlé pour développer leurs applications. Et pensant qu'un tiers voudra probablement un jour s'interfacer avec leur logiciel, elles vont aussi implémenter leurs propres API.

Maintenant supposons que ce soit votre boulot d'écrire un outil qui soit une interface de ces 3 applications.

Ugh. Vous allez devoir apprendre 3 API différentes. Et je parie que vous voudriez des boutons qui correspondent directement aux méthodes que vous appelez pour chaque API. Ça semble logique, non ? Je veux dire, comment feriez-vous autrement ? Ok, on ne parle que de 3 API et vous connaissez de bon ouvrages qui ont des design patterns qui vont vous permettre de réduire cette complexité (et de rester aimable avec vos collègues par la même occasion).

Et pour un million d'API ?

Revenons au navigateur. Lorsque vous l'installez sur votre ordinateur, il n'a aucune idée des sites que vous allez vouloir visiter. Par contre, il peut communiquer avec n'importe lequel de ces sites. Mais pas seulement, vous pouvez réaliser des actions sur ces sites : vous pouvez acheter de la musique, réserver des billets d'avion et avoir des vues satellites de votre maison.

Est-ce magique ? Réfléchissez un moment à l'impossibilité d'une telle approche si chaque site avait sa propre API. Pour acheter un livre sur Amazon, le navigateur aurait dû savoir appeler la méthode Amazon.Acheter(). Et il aurait dû appeler la méthode AirFrance.VérifierVols() lorsque j'ai cliqué sur le bouton « Vérifier les vols ». Vous ne pouvez tout simplement pas développer un outil qui permette d'appeler des millions d'API différentes.

C'est la raison pour laquelle le web n'a pas été designé avec une architecture RPC. Il a été designé avec une architecture REST.

Une architecture orientée ressource

D'après Wikipedia, REST signifie Representational State Transfer. Bon... peu importe. Cela signifie simplement qu'en lieu et place des noms avec des verbes arbitraires associés, chaque nom (que nous appellerons maintenant ressource) aura le même nombre fini de verbes. En d'autres termes, chaque ressource aura la même API. Les méthodes clés de cette API autorisent chaque client à :

• avoir une vue en lecture seule de la ressource ;
• créer une nouvelle ressource ;
• mettre à jour les attributs d'une ressource ;
• supprimer une ressource.

Attendez ! Laquelle de ces méthode permet « d'acheter ce livre » ? Laquelle permet de « chercher les vols entre Paris et Marseille mardi prochain » ? Laquelle me permet de zoomer d'une ville à une rue sur une carte ? Et laquelle permet à un utilisateur de se connecter à un site ?

Architecture RESTful

Nous sommes les dépôts

À partir de maintenant, pensez à votre application comme étant rien d'autre qu'un dépôt à ressources. Qu'est-ce qu'un dépôt ? Subversion est un bon exemple de dépôt de code source. MySQL est un dépôt de données relationnelles. Vous pensez à d'autres exemples ?

Pour le moment, j'ai juste besoin de prendre un exemple de dépôt que l'on puisse utiliser dans la suite de ce billet.

Le pire exemple au monde

Vous travaillez pour BiologeekAir, et vous devez développer leur infrastructure logicielle from scratch.

• Vous avez besoin d'un client riche, une interface permettant de saisir les informations de vol. Un vol est juste la définition d'un avion allant d'une ville à une autre à un moment donné.
• Vous voulez une interface web pour les employés de l'aéroport. Vous voulez que les passagers puissent vérifier le statut du vol à partir de leur téléphone portable.
• Et votre boss veut que vous créiez une belle API basée sur XML que les tiers pourront utiliser pour mettre à jour les gigantesques affichages de départs et d'arrivées de l'aéroport.

Ça semble être un projet alléchant, non ? Souvenez-vous de la première partie, nous avons décrit une architecture orientée objet traditionnelle et la façon dont il faut commencer en décrivant votre problème pour identifier les noms (qui deviendront vos objets) et les verbes (qui deviendront les méthodes). Imaginez juste le nombre de design patterns géniaux que vous allez pouvoir mettre en œuvre ! Vous ne pouvez plus résister à l'envie de dessiner un énorme diagramme UML au tableau et d'enchaîner avec quelques diagrammes d'interactions ! Oh, vous imaginez déjà les méthodes VolsPrévus.AnnulerVol() et Vol.Retard().

Désolé David. Depuis que vous utilisez REST, une grande partie de votre design est déjà fait pour vous ! En fait, la seule chose qu'il vous reste à faire est d'identifier vos ressources.

Laissez-moi le répéter, au cas où vous ne m'auriez pas entendu avec le raffut que font vos marqueurs effaçables, car c'est vraiment important.

Ne faites qu'identifier vos ressources.

Dans notre exemple, je peux rapidement identifier quelques noms clés : avions, aéroports et vols. Je vais probablement en trouver davantage ensuite mais c'est déjà un bon début.

Comment les interfaces clients vont-elles accéder à chacune de ces ressources ? Les URL ont été inventées pour ça. (Vous savez ce que signifie le L de URL n'est ce pas ?) Le « localisateur » de chaque ressource suit un pattern simple. Par exemple :

• /aeroports pour la liste des aéroports
• /avions pour la liste des avions
• /vols pour la liste des vols

et :

• /aeroports/ory pour Paris Orly
• /avions/ZJ3543 pour l'avion identifié par le numéro de série ZJ3543
• /vols/451 pour le vol #451

Quatre méthodes

Ok, une fois vos ressources identifiées, REST définie les 4 méthodes (ou verbes en langage HTTP) que chacune de vos ressources peuvent implémenter :

• GET : donnez moi une vue en lecture seule d'une instance d'une ressource depuis le dépôt.
• POST : j'ai une nouvelle instance d'une ressource que je veux ajouter au dépôt.
• PUT : je veux mettre à jour une ressource existante dans le dépôt.
• DELETE : je veux supprimer une instance d'une ressource du dépôt.

Ça vous semble familier ? Avec Subversion, GET est similaire aux commandes « checkout » ou « update ». POST correspond à la commande « add » et DELETE à « delete ». Dans l'exemple avec MySQL, GET revient à faire un SELECT, POST un INSERT, PUT est semblable à UPDATE et DELETE, et bien, DELETE.

Wow. Nous avons nos ressources et nous avons nos méthodes. On peut arrêter ici le design et commencer l'implémentation.

Appeler ces méthodes avec HTTP

Les applications web utilisent HTTP pour permettre au serveur et au client de communiquer ensemble. On peut maintenant préciser la première partie qui était restée assez floue. Que se passe-t-il vraiment lorsque vous tapez une adresse dans votre navigateur ? Le navigateur met en forme un message HTTP pour appeler la méthode GET de la ressource identifiée par l'URL que vous lui avez fourni.

Vous pouvez aussi appeler la méthode POST à partir de votre navigateur - mais seulement s'il y a un formulaire <form> sur la page. (Ok, pas exactement grâce à AJAX mais oublions pour le moment). Les formulaires peuvent envoyer des données à une URL particulière. Lorsque vous soumettez un formulaire, le navigateur appelle la méthode POST, passant l'URL ainsi que certaines données représentant la ressource qu'il doit ajouter ou modifier.

Vous ne pouvez pas appeler PUT ou DELETE avec votre navigateur avec du HTML habituel. Ce qui est bien malheureux. Bien que chaque serveur HTTP dans le monde sache gérer les appels aux méthodes PUT et DELETE, il n'y a pas de procédure standardisée pour faire ces appels avec du HTML. Vous devez inventer votre propre façon de faire pour signaler au serveur que vous essayer de faire des appels à PUT ou DELETE.

En résumé : vous pouvez faire correspondre votre API REST avec les verbes HTTP mais il n'y a aucun tag HTML qui permette de faire des appels à PUT ou DELETE. Le client et le serveur doivent se mettre d'accord sur une convention à utiliser pour simuler les méthodes PUT et DELETE.

On y est presque

Maintenant que notre design est au point, nous l'implémenterons prochainement avec Rails Django ;-).

Réactions du traducteur

Bon vous l'aurez compris, les prochains billets ne seront pas des traductions d'exemples d'implémentation avec Ruby on Rails mais des articles originaux pour voir ce qu'il est possible de faire avec Django. Plusieurs projets ont vu le jour et vont tenter de s'unifier pour arriver à une solution cohérente et facilement intégrable. Bon accessoirement, j'aimerais bien mettre en place professionnellement une telle architecture donc ça m'intéresse beaucoup.

En ce qui concerne REST, sa principale limitation vient de la non standardisation des méthodes PUT et DELETE dans les navigateurs. Je pense que c'est l'un des freins actuel à son adoption face à d'autres alternatives. Néanmoins, la possibilité de mettre en place du REST facilement côté serveur avec la dernière version de Ruby on Rails va, je l'espère, un peu démocratiser tout ça. Corrigez-moi si je me trompe mais RoR a choisi de placer une champ caché avec l'attribut method="PUT" (ou DELETE) pour gérer les différentes possibilités. Espérons que de telles pratiques deviennent la norme de façon à ce que REST devienne réellement la référence en terme d'interopérabilité entre les différents services web.

Ressources

En français

• Apprendre REST - un style d'architecture du Web
• soap vs. rest : choisir la bonne architecture web services
• Traduction du chapitre de la Thèse de Roy T. Fielding relatif à REST

En anglais

• How I Explained REST to My Wife (et maintenant traduit en français ! Merci Karl).
• The REST Dialogues : c'est un catégorie de son blog, il faut donc commencer par le dernier, c'est long mais ça en vaut la peine, surtout qu'il y a une vraie réponse d'un architecte eBay qui a joué le jeu (il a répondu à d'autres aussi, généralement le lien est en commentaire).

Je n'en mets pas plus car vous allez très vite être submergé de liens, c'est juste pour vous mettre en appétit, j'espère que vous êtes maintenant convaincu que REST est plus qu'une alternative à SOAP !

[edit] : un nouveau billet intitulé L'architecture orientée ressource pour faire des services web RESTful précise de nombreux points sur l'architecture REST non couverts dans ce billet.