larlet-fr-david/david/blog/2014/api-internes-hypermedia/index.md

title: API internes et Hypermedia
slug: api-internes-hypermedia
date: 2014-01-14
chapo: Plutôt que d'utiliser le Web à mauvais escient, peut-être qu'il appartient aux développeurs web de s'ouvrir à d'autres options…

> “Small pieces loosely joined,” David Weinberger’s appealing [theory of the Web](http://www.smallpieces.com/index.php), has much to say to programmers as well. It always inspires me to reduce the size of individual code components. The hard part, though, is rarely the “small” – it’s the “loose”.
>
> <cite>*[Transformative Programming](http://programming.oreilly.com/2013/10/transformative-programming.html)*, 	Simon St. Laurent</cite>

Je coopère depuis maintenant 6 mois avec l'équipe des paiements du [Marketplace de Mozilla](https://wiki.mozilla.org/Marketplace). C'est typiquement un cas où [une grosse application monolithique](http://zamboni.readthedocs.org/en/latest/) a été scindée [en plusieurs petites](http://webpay.readthedocs.org/en/latest/) [API qui communiquent](http://solitude.readthedocs.org/en/latest/) [entre elles](http://zippypayments.readthedocs.org/en/latest/). On retrouve donc bien le *small pieces* (même si c'est discutable) mais qu'en est-il du *loosely joined* ? Ces différentes briques communiquent entre elles via HTTP en essayant de le respecter au mieux mais la partie *hypermedia* relève de l'anecdotique avec quelques liens pas forcément exploités. Dans quelle mesure est-ce problématique au quotidien ?

**Le couplage fort nécessite parfois la modification du client et du serveur de manière simultanée.** Rien de grave lorsque l'on contrôle les 2 mais la seule alternative serait de coder de manière très défensive avec tout le *code mort* que cela occasionne sur le moyen terme. L'utilisation d'*hypermedia* permettrait de réduire cela (pas forcément d'y pallier totalement) en proposant de nouvelles façons de parcourir le graphe sans qu'elles deviennent indispensables. La logique défensive ne se situerait plus au niveau du client mais du serveur qui devrait gérer *le cycle de vie de ses URI*.

**Il peut y avoir ambiguité dans les identifiants.** Parfois ce sont des *UUID*, d'autres fois des *primary keys*, d'autres fois des *ids*, d'autres fois enfin des *URI*. Difficile de s'y retrouver et de faire la distinction entre ce qui est unique ou non, se baser sur *un schéma d'URI cohérent* permettrait de lever cette ambiguité tout en conservant un vocabulaire commun entre les différents projets. Plus l'architecture devient complexe, plus la cohérence devient importante et nécessite d'avoir une vision à long terme. Non pas [en anticipant les problèmes](/david/blog/2013/graphes-discussions/) mais en se laissant la possibilité d'évoluer sans tout casser.

**La logique est cachée dans le code.** Et la documentation lorsqu'elle est à jour et pertinente. Il est quasi-impossible de comprendre les interactions entre les différentes parties en analysant leurs seuls échanges ce qui rend difficile l'intégration sur un projet. *La vision d'ensemble est endommagée par une telle pratique.* Il n'est pas possible de naviguer dans le graphe des interactions pour en comprendre les tenants et les aboutissants, l'effort de documentation se trouve être décuplé.

Est-ce que l'utilisation d'*hypermedia* était indispensable dans ce cas là ? Pas forcément, avec le recul je me demande même si l'utilisation d'HTTP est une bonne chose pour ce style d'API internes. Quitte à garder un couplage fort, l'utilisation de protocoles binaires comme [Apache Thrift](https://thrift.apache.org/) ou [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) permettrait de gagner en performances sans forcément complexifier le code. La culture s'en trouverait par contre certainement altérée en perdant le côté Web, **mais plutôt que d'utiliser le Web à mauvais escient, peut-être qu'il appartient aux développeurs web de s'ouvrir à d'autres options…**

Pour en revenir à [l'article initialement lié](http://programming.oreilly.com/2013/10/transformative-programming.html), je m'interroge de plus en plus sur cette notion de flux de données et sur l'importance que l'on accorde à son stockage, sa serialization, sa transformation, son transport et son accès. *Chacune de ces étapes dans la vie d'une donnée devrait être traitée avec le même soin.*