larlet-fr-david/david/blog/2013/api-hommes/index.md

title: Des API et des hommes
slug: api-hommes
date: 2013-04-25
chapo: Demandez vous si votre API est navigable, fait partie intégrante du Web et nécessite une documentation.

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](http://opikanoba.org/tr/fielding/rest/)) et qui a écrit [un billet on ne peut plus clair en 2008](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) :

> 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](http://json-ld.org/) (LD pour Linked Data), proche des concepts du Web Sémantique ;
* [HAL JSON](http://stateless.co/hal_specification.html) le plus simple, peut-être un peu trop ;
* [JSON Collections](http://www.amundsen.com/media-types/collection/) que je n'ai pas essayé ;
* [Siren](https://github.com/kevinswiber/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](/david/talks/#20).*