English version available

L’article « API, REST, JSON, XML, HTTP, URI… Vous parlez quelle langue en fait? » exposait quelques principes sur les webservices et les technologies associées, en particulier REST. Maintenant que vous êtes incollable sur le sujet, continuons un peu et introduisons HATEOAS. Bien que le nom soit un peu barbare, il n’y a aucun rapport avec un quelconque personnage du seigneur des anneaux!

Reprenons l’exemple du trajet en train du premier article. Notez que tous les exemples qui suivent sont en JSON, mais l’utilisation du XML est tout à fait possible.

{
  "trainNum": 123456789,
  "departure": {"station": "Bruxelles-Central", "time": "07:28"},
  "arrival": {"station": "Liège-Guillemins", "time": "08:25"}
}

Ce message décrit un trajet en train en donnant diverses informations telles que le numéro du train, les gares de départ et d’arrivée et les horaires. Par contre, il n’y a aucune information liée au contexte. En se basant uniquement sur le contenu de ce message, on ne peut pas deviner sa provenance ou le moyen pour obtenir davantage d’informations (sur le trajet, le train, etc.). C’est le moment où notre cher compagnon HATEOAS intervient.

HATEOAS est l’acronyme de Hypermedia as the Engine of Application State. Tout de suite, c’est plus clair! Non? Ok, moi non plus. Concrètement, c’est un moyen d’ajouter des informations contextuelles à un message. On parle de la « contrainte » HATEOAS sur REST car le but est que ces données ajoutées respectent un format bien défini et universel. Ce standard (comme tous les autres) est indispensable afin d’éviter que chacun crée son propre format maison et que cela devienne spécifique par API. On perdrait alors en intérêt et en compréhension.

Dans le cas de mon trajet, il serait intéressant d’avoir les coordonnées du train suivant et précédent. Pour obtenir ce lien entre les trajets et respecter la contrainte HATEOAS, le message devient:

{
  "numTrain": 123456789,
  "departure": {"station": "Bruxelles-Central", "time": "07:28"},
  "arrival": {"station": "Liège-Guillemins", "time": "08:23"},
  "_links": {
    "self": {
      "href": "http://www.triptrain.com/displayTrip?numTrain=123456789&departureStation=Bruxelles-Central&departureTime=07:28"
    },
    "nextTrain": {
      "href": "http://www.triptrain.com/displayTrip?numTrain=987654321&departureStation=Bruxelles-Central&departureTime=08:01"
    },
    "previousTrain": {
      "href": "http://www.triptrain.com/displayTrip?numTrain=147258369&departureStation=Bruxelles-Central&departureTime=07:01"
    }
  }
}

Le bloc de données existant reste inchangé et un bloc de liens a fait son apparition. Les webservices en REST peuvent donc être adaptés sans avoir besoin de toucher à l’existant, le risque de régression est ainsi minimisé.

Le message a maintenant un sens beaucoup plus fonctionnel. A partir d’un trajet, je suis capable de passer au suivant ou au précédent. Je dois avouer que l’exemple est peut-être un peu limité, mais imaginez le principe dans d’autres contextes.

D’une certaine manière, l’API s’auto-découvre et le message s’auto-décrit. La réponse à une requête permet d’en faire une autre sans forcément connaitre à l’avance toutes les méthodes disponibles sur l’API. HATEOAS améliore grandement la lisibilité de vos API, mais l’intérêt devient réel lorsque les consommateurs du webservice utilisent ces nouvelles informations.

Il y a cependant un revers à la médaille: HATEOAS est relativement jeune et la spécification n’est pas clairement définie. D’ailleurs où est-elle? D’autres personnes se sont posé cette question, il semblerait que vous pouvez la trouver ici: HAL – Hypertext Application Language specification. Il y a aussi cette page bien plus lisible et sur laquelle vous trouverez plusieurs liens intéressants dans la partie « Quick links ». Je vous conseille leur lecture si vous souhaitez approfondir le sujet.

 English version available

REST (REpresentational State Transfer) est un standard utilisé pour l’élaboration de webservices. Un service web comme son nom l’indique rend accessible un service via des technologies web. Autrement dit, le système appelant demande un service au système appelé via le web qui en retour lui fournit une réponse, celle-ci peut être négative si l’appelé ne veut ou ne peut pas honorer le service demandé. Ce principe d’architecture permet à des systèmes de communiquer entre eux. L’intérêt est encore plus évident pour des systèmes hétérogènes qui utilisent des technologies différentes les rendant incompatibles (en communication « directe »).

Un standard qui utilise des… standards

Avec REST, la communication se base sur des technologies Web et plus exactement sur le protocole HTTP (Hypertext Transfer Protocol) et les URI utilisés par le Web. Les messages sont transmis dans un format standardisé. Pour l’intégration des réponses, on utilise généralement le format JSON (JavaScript Object Notation), plus léger et moins verbeux que le XML (eXtensible Markup Language), mais ce dernier peut bien sûr être utilisé.

A titre illustratif, voici la représentation (volontairement simplifiée) d’un trajet en train:

En JSON:

{
	"trainNum": 123456789,
	"departure": {
		"station": "Bruxelles-Central",
		"time": "07:28"
	},
	"arrival": {
		"station": "Liège-Guillemins",
		"time": "08:25"
	}
}

Et l’équivalent en XML:

<trip>
	<trainNum>123456789</trainNum>
	<departure>
		<station>Bruxelles-Central</station>
		<time>07:28</time>
	</departure>
	<arrival>
		<station>Liège-Guillemins</station>
		<time>08:25</time>
	</arrival>
</trip>

L’interprétation des données est très facile tant ces formats de représentation sont simples à lire. La complexité est bien souvent liée à la donnée elle-même. Le fait de parler de trajets en train ne pose ici pas de difficultés.

A l’heure d’aujourd’hui, les webservice de type REST se démocratisent rapidement, cela pour plusieurs raisons:

• La simplicité évidente
• L’utilisation du protocole HTTP dont les qualités ne sont plus à démontrer. Le protocole actuel est en version 1.1, datant de 1999 (avant même IE6). En informatique, on peut dire que c’est très vieux…
• Les systèmes sont de plus en plus modulaires, le besoin d’interaction et de communication ne cesse de grandir.

Et dans la « vraie » vie alors? C’est utile REST et les webservices?

Eh oui! Vous l’utilisez même peut-être tous les jours sans y prêter attention. Par exemple, le fait que vous vous connectez à une application via votre compte Facebook implique l’appel à un webservice. L’application tierce interroge Facebook pour savoir si vous l’avez autorisé ou non à accéder à vos informations (adresse email, nom, liste d’amis ou autres), le cas échéant, elle fournit ces informations à l’application. Cet échange vous permet alors de vous authentifier à l’application tierce. Un tel mécanisme d’authentification/création de compte est de plus en plus utilisé, car:

• Beaucoup de personnes sont sur les réseaux sociaux (Twitter, Facebook, Google+)
• Cela évite d’avoir à créer un nouveau compte (et donc de fournir un énième mot de passe).

Par contre, il devient important de bien sécuriser son compte social, car si celui-ci est piraté, tous vos comptes associés deviennent vulnérables. A ce propos, n’hésitez pas à lire ou relire l’article « Quelques règles essentielles pour éviter de se faire pirater ses comptes ».

Techniquement, comment cela se passe-t-il?

L’appel à un webservice se fait via un appel HTTP standard et on reçoit une réponse tout aussi standard. Au niveau de la requête (demande de service), cela peut être un GET (pour récupérer des données en lecture seule), un POST (pour soumettre des données dans le but d’une modification), la liste complète des verbes HTTP est ici. La réponse dépendra de la requête et des données fournies, cela peut être la fameuse réponse 404 pour indiquer que le contenu est introuvable, un code 403 dans le cas où vous n’avez pas les droits d’accès/modification nécessaires, vous trouverez la liste complète des codes de retour ici. Bien évidemment, il ne faut pas oublier le code 200 qui indique que tout s’est bien passé (statut OK), avec potentiellement une réponse au format XML/JSON.

La mise en place d’un webservice doit suivre des bonnes pratiques. Voici des exemples de ce qu’il ne faut pas faire:

• Utilisation d’une requête de type POST pour récupérer des données alors qu’un GET aurait été plus approprié (car on ne modifie pas l’état des données)
• Renvoi d’une valeur vide (null) avec un code 200 alors que les codes 204 ou 404 sont justement prévus pour cela.

Aussi, il est très important que tous les appels soient idempotents, c’est à dire, dans le cas où on envoie plusieurs fois la même requête, la réponse doit être consistante. Par exemple :

• Je fais un POST pour modifier des données, je reçois un retour 200 comme quoi la donnée a été modifiée
• Si je refais le même POST, je dois recevoir un code 304 comme quoi la donnée n’a pas été modifiée.

Cela ne doit jamais poser de problème de faire plusieurs fois un même appel, il faut veiller à ce que cela soit géré par le système et qu’il n’y ait pas d’effet de bord.

Parlons API

Jusqu’à maintenant, nous avons vu que les webservices permettent à des systèmes existants de communiquer entre eux, mais ce n’est pas le seul cas d’utilisation. Les développeurs peuvent aussi s’appuyer sur des webservices mis à leur disposition pour développer de nouvelles fonctionnalités ou même une application tierce. Dans ce cas, on parle d’API: Application Programming Interface (Interface de programmation).

Pour continuer sur l’exemple des réseaux sociaux, prenons l’API de Twitter. Twitter met à disposition un ensemble de méthodes basées sur REST qui permettent de récupérer et manipuler les tweets. Il y a beaucoup de services disponibles, vous pouvez consulter la liste complète des webservices Twitter ici.

Utilisons un webservice de Twitter qui se base sur un GET. Les requêtes de type GET sont les plus simples à tester, car un simple clic du navigateur permet de créer et envoyer la requête. L’URL suivante permet de faire un GET pour obtenir la liste des tweets français qui concerne la coupe du monde de cette année.

• https://api.twitter.com/1.1/search/tweets.json?q=worldcup2014&lang=fr

En fait, vous verrez que la réponse ne contient aucun tweets et contient un message d’erreur. Il faut aussi ajouter les informations d’authentifications à la requête, le simple clic finalement ne suffit pas. En effet, les API sont naturellement protégées et demandent d’être enregistré avant de pouvoir être utilisées. Bref, vous avez compris le principe et aussi reçu une réponse en JSON de la part de Twitter (même si c’est un refus…).

Nous avons principalement parlé de l’API de Twitter, mais il y a des milliers de webservice et API disponibles. L’API de Google Maps permet au dévelopeur d’intégrer des cartes personnalisées, cette ouverture est sans doute un des ingrédients qui ont permis un tel succès. En effet, beaucoup d’applications et de sites internet se basent sur les données cartographiques de Google pour proposer de nouveaux services, à noter aussi qu’un véritable business plan est proposé par la firme.

Enfin, si vous êtes curieux, vous pouvez faire un tour sur ProgrammableWeb, un site collaboratif qui référence beaucoup d’API.