Des API et des hommes

Les API actuelles — s’auto-proclamant RESTful — nécessitent bien souvent de développer un client qui leur est propre pour accéder aux données en raison de leurs spécificités. Au mieux, ces API utilisent HTTP à bon escient et font transiter du JSON à partir d’URL « propres ».

Cela semble bien éloigné de la vision de Roy T. Fielding (qui a défini REST en 2000 dans sa thèse) et qui a écrit un billet on ne peut plus clair en 2008 :

A truly RESTful API looks like hypertext. Every addressable unit of information carries an address.

Puis surenchérit en commentaire :

Think of it in terms of the Web. How many Web browsers are aware of the distinction between an online-banking resource and a wiki resource? None of them.

5 ans plus tard, on en est encore à réécrire un client pour chaque API ce qui équivaudrait à écrire un navigateur propre à chaque site web visité ! Comment y remédier facilement ? Revenir à la partie oubliée de REST : les liens.

Si votre API devient navigable, en liant chaque ressource présentée depuis sa racine, un client générique va pouvoir la parcourir de proche en proche en suivant les liens comme un utilisateur le fait sur le Web.

Cela résout énormément de problématiques à la fois lorsque l’on prend cette approche :

Ces questions se sont posées pour les sites Web également il y a des années : souvenez-vous des sites avec un /v4/ dans l’URL ou d’une page d’accueil expliquant comment accéder aux différentes parties du site en « cliquant ici ».

Bien sûr tout cela implique d’avoir un format qui soit hypertexte (pas JSON donc) comme XHTML ou Atom. Si vous voulez vraiment adapter votre JSON actuel il existe 4 implémentations tentant d’introduire des liens typés :

Lorsque vous voulez fournir un moyen d’accéder à vos données via une API hypermedia, mettez vous à la place du développeur et demandez vous si votre API est navigable, fait partie intégrante du Web et nécessite une documentation.

Ce billet fait suite à mon intervention à Mix-IT lors d’un lightning talk dont vous pourrez retrouver le support sur la partie dédiée.

Discussion suite à l’article :

Je viens de lire ton article "Des API et des hommes" avec un grand intérêt. Je me permets de te contacter car certaines choses ne sont pas encore bien claires pour moi.

Bien que tu ne le mentionnes pas, je pense que tu fais référence au principe HATEOAS qui fait défaut dans la plupart des API dite REST. Si j’ai bien compris HATEOAS, le but est d’utiliser des URI vers les différentes ressources liées à la ressource demandée. On peut ainsi naviguer dans l’API comme on naviguerait sur un site web. (corrige moi si je me trompe)

Première point, je ne vois pas comment on pourrait faire autrement que de réécrire un client spécifique pour chaque API. Par exemple, je développe un équivalent à Google Reader possédant une API, et je souhaite avoir une application Android/IOS/Desktop/... pour consulter mes flux (les marquer comme lu, etc.). Il faut bien développer un client pour utiliser cette API. Je ne vois pas comment faire autrement.

Deuxième point, je me demande pourquoi il est nécessaire d’avoir un format hypertexte, et du coup de laisser tomber JSON. Pourquoi ne pas développer une API qui retourne des liens dans du JSON ? Parce que ce ne serait pas interprété comme des liens dans le navigateur ?

Et pour finir, as-tu un exemple d’API navigable tel que décrit dans ton article ? Je suis curieux de voir à quoi ça ressemble en vrai.

Laurent Meunier, le 2013-04-26 à 09:49