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

‍

Comme pour les API qui ne supportent pas l'hypermedia, trois types d'outils peuvent s'avérer très utiles : (i) les formats de message (ex : JSON), (ii) les frameworks et (iii) les clients REST Javascript.

A l'inverse des APIs dites RESTful, il n'existe pas encore de standard pour les API Hypermedia. Les frameworks et clients Javascript sont donc peu nombreux.

Regardons toutefois quelles solutions s'offrent à nous dans chaque catégorie. Nous avons trouvé 9 formats et 7 frameworks qui permettent de développer des APIs hypermedia, ainsi que deux clients HTTP JavaScript pour interagir avec une API hypermedia depuis un frontend.

Pour se lancer, des tutoriels sont disponibles sur le Web tant en français qu'en anglais, pour une majorité des langages de programmation populaires.

Formats de message

Parmi les formats de message, on dénombre : HAL, Collection+JSON, Siren, Uber, Mason, Json:Api, OData, JSON-LD (à combiner avec Hydra) et Atom.

Le plus complet est Mason, il a de plus l'avantage d'être relativement simple à lire. Ceci dit, HAL est le format le plus utilisé que nous ayons vu. Son manque d'expressivité nous a toutefois amené à l'enrichir sur chacun des projets sur lesquels nous l'avons choisi.

Attention toutefois, enrichir un format selon son besoin fait que les outils le supportant seront incapables d'exploiter ce vocabulaire supplémentaire.

JSON-LD présente quant à lui l'avantage d'être compatible Linked Data, ce qui peut s'avérer très intéressant. Le Linked Data, traduit Web des données, est décrit sur Wikipedia comme_ “une initiative du W3C (Consortium World Wide Web) visant à favoriser la publication de données structurées sur le Web, non pas sous la forme de silos de données isolés les uns des autres, mais en les reliant entre elles pour constituer un réseau global d'informations”_. Nous vous en disons plus à ce sujet dans la suite de cette série.

Afin de simplifier votre choix parmi ces technologies, nous les avons classées dans le tableau suivant. Les catégories correspondent aux niveaux d’un modèle de maturité créé pour les APIs Semantic REST, WS3. Ce modèle enrichit le très répandu modèle de maturité de Richardson.

Frameworks

Nous avons trouvé 5 frameworks supportant l'hypermedia, couvrant au total 5 langages différents. L'un d'entre eux, Restfulie, est disponible dans trois langages : .NET, Java et Ruby. Le choix étant limité dans chaque langage, nous n'approfondirons pas la question dans cette section. Nous espérons que le tableau suivant pourra vous aider à orienter votre choix.

Si aucun framework ne vous satisfait, il vous sera probablement nécessaire de développer une librairie afin de supporter le format de message que vous aurez choisi et de générer les hyperliens.

Dans ce cas, pour transmettre la description des opérations disponibles dans la réponse de l'API, nous vous recommandons d'utiliser celle de la documentation Swagger/OpenAPI. En ce qui concerne la génération des liens, une solution relativement simple à maintenir et conceptualiser est de modéliser les ressources avec des machines à états finis. Ensuite, il convient d’utiliser l'état de la ressource pour déterminer les opérations qui sont disponibles.

Clients REST Javascript

Il existe quelques clients REST pour Javascript, notamment Traverson et Ketting, tous les deux bien documentés. Traverson supporte HAL, Mason, Collection+JSON, Siren et Uber tandis que Ketting uniquement HAL et Json:Api. Ils peuvent tous deux être étendus avec des parseurs customs et sont compatibles Typescript.

Un style d'API encore peu répandu

Ce type d'API est encore peu répandu et a des détracteurs relativement violents sur le sujet, pour des raisons qui sont tout à fait compréhensibles.

La première, c'est tout simplement le manque de standard. Sans eux, il est nécessaire de supporter plusieurs formats qui peuvent devenir populaires comme disparaître, remplacés par de nouveaux venants. Cette instabilité a quelque chose de décourageant.

Le second point, c'est que les outils les plus populaires n'exploitent pas les possibilités offertes par ces APIs. Postman ne sait pas comment se comporter, Angular n'a pas de support par défaut, les APIs du navigateur non plus d'ailleurs, ni même les routeurs frontend ou les outils de test automatisés. Tous ces outils nous sont nécessaires au quotidien, mais ne nous encouragent malheureusement pas à passer à l'hypermedia. Nous croisons les doigts pour que le mainteneur de l'un d'eux nous lise.

N'oublions toutefois pas que ce type d'architecture est une solution au fort couplage clients-serveur devenu légion, et que malgré son manque de maturité du côté des APIs, il reste très intéressant.

Conclusion

Dans cet article, vous avez découvert trois types de technologies qui peuvent vous permettre de développer des APIs hypermedia dès aujourd'hui.

Dans le prochain billet de cette série, nous nous intéresserons à la sémantique interprétable par la machine. Des APIs automatiquement compatibles avec les assistants vocaux, des moteurs de recherche présentant exactement l'information recherchée, moins de documentation à écrire et des librairies plus intelligentes, cela ne vous tente-t-il pas ?