Note : Ce contenu a été créé avant que Fabernovel ne fasse partie du groupe EY, le 5 juillet 2022.

‍

Imaginez un instant que tous les liens des sites webs que vous utilisez disparaissent ! En lieu et place, vous auriez un manuel d'utilisation qui vous explique comment construire les URLs par vous même, et comment construire une requête HTTP afin de commenter une photo sur Facebook. Allez, disons que pour votre confort vous automatisez la création des liens avec du code, nous sommes quand même en 2019 ! Et maintenant, chaque fois que le site est modifié, et bien vous devez modifier votre code. Ça vous semble absurde, non ? C'est pourtant le quotidien des développeurs qui consomment des APIs. Regardons ensemble comment l'ajout de liens dans les APIs permet d'éviter cela.

APIs, REST, HATEOAS de quoi allons-nous parler ?

Une API Web fournit une liste de services interrogeables, par exemple récupérer la météo du jour, ou poster un tweet. Chaque service est accessible à une URL qui lui est dédiée, par exemple https://api.twitter.com/1.1/statuses/update.json pour poster un nouveau tweet.

Aujourd’hui, la majorité des APIs se dit RESTful, c’est à dire respectant l’architecture REST. Son auteur, Roy Fielding, l’a créée dans le but que le web soit fait de systèmes performants, fiables et extensibles. Extensible veut dire qu’ils réutilisent les fonctionnalités fournies par d’autres systèmes (les APIs), et que ces derniers peuvent être mis à jour sans affecter ceux qui s’en servent.

C’est ce dernier point qui nous intéresse aujourd’hui. Pour pouvoir se mettre à jour sans affecter ses clients, un système doit respecter une contrainte que Roy Fielding a appelée HATEOAS.

HATEOAS veut dire "Hypermedia As The Engine Of Application State", que l'on peut traduire par "l'hypermedia comme moteur de l'état de l'application". L'idée est que des liens, fournis par l'API, guident l'utilisateur dans son utilisation de l'API. Autant c'est la norme dans les pages HTML, autant absolument pas du côté des APIs. C'est même un concept que beaucoup de développeurs que nous avons rencontré peinent à comprendre pour les APIs, alors qu'il leur est naturel du côté HTML.

Malgré l’habitude qu’ont pris les créateurs d’APIs à les qualifier de RESTful, 95% d’entre elles ne respectent pas la contrainte HATEOAS. La majorité de ces APIs devraient plutôt être qualifiées d’API HTTP, car elles sont accessibles par HTTP mais ne respectent pas REST. Ceci dit, dans l’usage, on ne peut plus vraiment changer cette habitude prise. C’est pourquoi les créateurs d’APIs qui respectent HATEOAS les ont appelées APIs HATEOAS, ou APIs Hypermedia, Hypermedia étant le H de HATEOAS.

Nous utiliserons un dernier concept : les ressources. Prenons par exemple l'API d'un site de e-commerce. Elle aura probablement quatre ressources : (i) les utilisateurs, (ii) les articles, (iii) les commandes et (iv) le panier. Chaque ressource a des opérations qui lui sont propres. Par exemple, l'ajout d'un article au panier est une opération de la ressource panier.

Pourquoi des liens ?

Lançons-nous dans le vif du sujet, la partie fun !

Pour comprendre quel usage faire des liens dans les APIs, regardons quel usage nous en faisons du côté HTML. Prenons en exemple l'image ci-dessous.

Sur cette image nous retrouvons les cinq usages principaux des hyperliens. Illustrons-les encadré par encadré :

1. "Back to shop" indique un lien vers une autre ressource à laquelle il est pertinent d'accéder depuis la page en cours de visite. Le lien est alors utilisé comme recommandation.
2. "EC-GO Tryout Bag" propose un lien vers l'article mis dans le panier, qui est une autre ressource que le panier actuellement affiché. Ici, le lien est utilisé pour lier une ressource embarquée dans la ressource observée.
3. "Add gift code" est un lien vers une opération. On peut ainsi en déduire que l'utilisateur a le droit d'ajouter un code de réduction. S'il n'était pas connecté ou l'avait déjà fait, le bouton ne serait pas affiché ou grisé. Ici, le lien sert à illustrer les droits d'accès de l'utilisateur.
4. Dans ”payment details”, deux choses sont intéressantes. La première, c'est que le lien indique la prochaine étape du processus d’achat qui est en train d'être suivi par l'utilisateur. Ce dernier n'a pas à connaître l'ordre des étapes à suivre pour effectuer sa commande, il lui suffit de cliquer sur suivant. La deuxième partie intéressante est le formulaire, il indique à l'utilisateur quelles informations entrer pour réaliser l'opération de paiement. Il n'est pas face à un unique champ texte qui l’obligerait à consulter les conditions de vente (la documentation) pour savoir quelles informations fournir.

Pour générer cette page, l'API pourrait avoir envoyé les données suivantes :

Si vous n'êtes pas habitué à lire du code, rassurez-vous, la capture ne présente pas du code avec de la logique ou quelque chose de complexe à interpréter, elle structure l’information. Vous pouvez le lire ainsi : votre commande (your_order) est composée des éléments identifiés par les codes “1234”, “5678”, “9ABC” (a utiliser pour récupérer davantage d’information sur ces articles, c’est un peu comme leur numéro de sécurité sociale à eux), son montant total (subtotal) est de 537 et ses frais de livraison (shipping) sont de 0. Même processus pour lire la suite.

Ensuite, c'est le code écrit dans le site web qui permet de déterminer quels liens afficher, comment générer le lien vers la fiche produit, quelles informations demander dans le formulaire, s'il faut ou non afficher un bouton pour donner à l'utilisateur accès à une certaine page ou action et quelle est l'étape suivante du processus.

Hormis les recommandations, toute l'information est aussi codée dans le serveur, parce qu'il doit vérifier que les demandes du site sont cohérentes et non des tentatives d'attaque. Ce code écrit sur la page web, qui contient des règles très spécifiques à l'API utilisée, crée un couplage fort avec le serveur qui fournit l’API. Dans un tel cas, où une page web (ou n’importe quel autre logiciel) consomme une API, on dit que cette page est un client de l’API. Comme plusieurs pages ou logiciels peuvent en être clients, on parle de couplage clients-serveur.

Comme nous l'avons vu dans le premier article de cette série, il est le premier facteur freinant la mise à jour technologique du SI. Dans notre sondage, il était aussi jugé par 30% des répondants comme l'un des trois plus gênants pour réaliser de nouvelles fonctionnalité dans un temps raisonnable.

Cela pose le problème suivant : si la règle métier change, par exemple deux étapes du processus de commande sont inversées (paiement et livraison), alors il faut modifier le code du site web et du serveur. Si au lieu d'un site web, il y en a des dizaines voire centaines, ce sont tous ces clients qu'il faut mettre à jour. Cette tâche, d’adapter son système à l'évolution d’une API utilisée se trouve être régulière pour un développeur.

En enrichissant l'API des hyperliens que la page web génère, il est possible de supprimer de cette dernière toutes les règles métier. La page devient ainsi un interpréteur de l'API. Elle continue de fonctionner même si l'API change, à condition toutefois qu'elle ait initialement été conçue pour s'adapter intelligemment. Voici un exemple de fichier que l'API aurait pu envoyer pour éliminer le couplage entre le client et le serveur :

Notons que la présence d'un lien indique que l'utilisateur a le droit de faire l'action ou d'accéder à la page concernée. A l'inverse, tout comme sur une page HTML, si le lien n'est pas présent, c'est que l'utilisateur n'a pas les droits.

Les exemples précédents utilisent des hyperliens vers d'autres pages webs ou opérations HTTP de l'API, sans expliciter le format de retour. L'idée de l'hypermedia est lier des ressources de type de média différents, comme des documents JSON, des images et des pages HTML. L'exemple ci-dessous illustre ce point.

Conclusion

Dans cet article, nous vous avons présenté quels usages nous pouvons faire des hyperliens dans les APIs et montré en quoi cela peut fortement réduire le couplage clients-serveur.

Dans le prochain billet de cette série, nous vous partagerons notre comparaison des 9 formats de messages et 7 frameworks qui permettent de développer des APIs hypermedia.