# ? Des API et des hommes Publié le 25 avril 2013

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 :

- versionnement : est-ce qu’un utilisateur se soucie de la version du site qu’il consulte ? Non. Il suit les liens et si la migration a bien été effectuée il y a des redirections et les codes HTTP appropriées pour gérer ses anciens favoris. Les formulaires ont été mis à jour avec le site et il suffit qu’il remplisse correctement ceux qui lui sont dorénavant présentés.
- URL propres : est-ce qu’un utilisateur se soucie de la beauté des URL qu’il parcoure ? Quand je vois la tête de celles produites par Google ou Amazon j’en doute. Un développeur ne devrait pas avoir à se soucier de cela si le client suit les liens qui lui sont proposés.
- documentation : est-ce qu’un utilisateur a besoin d’une documentation pour naviguer sur votre site ? De toute façon, il y a peu de chance qu’il la lise, en revanche il est utile de lui formuler des messages d’erreurs intelligibles lorsqu’il se trompe de chemin. Il peut être intéressant de faire un rappel sur le métier et les concepts abordés car le développeur — à la différence du visiteur — n’est peut-être pas concerné par le sujet de l’API en question.
- pagination : en utilisant les attributs permettant de typer la relation entre les liens, il est possible de fournir les liens vers la page suivante et précédente explicitement.

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 :

- JSON-LD (LD pour Linked Data), proche des concepts du Web Sémantique ;
- HAL JSON le plus simple, peut-être un peu trop ;
- JSON Collections que je n’ai pas essayé ;
- Siren le plus récent qui est en train de monter rapidement.

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