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

‍

Nous vous présentions dans les précédents articles de cette série comment les APIs Semantic REST, des APIs mixant hypermedia et sémantique peuvent sensiblement réduire le couplage clients-serveur et nous offrir de nouvelles possibilités.

Dans sa vision la plus complète, l’API Semantic REST exploite l’hypermedia pour guider l’utilisateur et est accompagnée d’une description sémantique très complète. La mettre en place nécessite beaucoup de travail, si bien que vous pourrez par exemple juste implémenter les fonctionnalités dont vous aurez vraiment besoin (ou envie, amusons-nous un peu tout de même). Ces concepts sont pour l’instant peu utilisés, les standards n’ont donc pas encore émergé. Difficile alors de vous dire : utilisez cette technologie-là, c’est LE standard du domaine, elle est très populaire, très complète, ce sera forcément un bon choix.

Non, à l’inverse, il convient plutôt d’identifier les technologies qui répondront à votre besoin. Nous vous présenterons tout d’abord un modèle de maturité, similaire à celui de Richardson, conçu pour les APIs Semantic REST. Ensuite, nous vous partagerons les tables de comparaison que nous avons faites, ainsi qu’un outil disponible en ligne, qui vous simplifiera la tâche.

Quels types de technologies ?

Vous aurez besoin de trois types de technologies pour concevoir de telles APIs :

1. Un format de messages, Data Interchange Format en anglais (aussi appelé media-type) qui supporte les contrôles hypermedia et l’ajout de sémantique ;
2. Un langage de description d’interfaces (Swagger en est un) qui offre le vocabulaire et une structure pour décrire votre API avec de la sémantique ;
3. Un framework, pour vous aider à implémenter votre API.

Choisir ses fonctionnalités

A chaque projet ses contraintes, à chaque équipe ses compétences et ses envies. Et puis il y a la question des délais. Comment choisir les fonctionnalités à implémenter ?

Nous pouvons par exemple nous aider d’un modèle de maturité. C’est une échelle qui fixe des niveaux de maturité. Chaque niveau inclut plusieurs fonctionnalités ou propriétés. Plus le niveau de maturité est élevé, plus l’API est riche en fonctionnalités. Dans l’univers REST, le modèle de Richardson est le plus populaire, avec ses “4 niveaux de REST”.

Aparté : le modèle “de Richardson” populairement diffusé n’est pas la version dont il est l’auteur. Martin Fowler en a modifié le nom des niveaux. Le reproche qui lui est fait est qu’il laisse à supposer qu’une API de niveau 3 est plus “mature” qu’une API de niveau 1. Elle sert en fait d’autres besoins. Ni l’une ni l’autre n’est meilleure, le niveau choisi doit être adapté au contexte. Article critique. Modèle originel.

Pour le concepteur, un tel modèle permet d’avoir une vision d’ensemble du type d'architecture visé. Il aide à choisir quels types de fonctionnalités favoriser ou écarter. Rien n’oblige à respecter les niveaux à 0 ou 100%, le tout est à adapter au contexte du projet. C’est pourquoi, après avoir choisi un niveau cible, il reste nécessaire d’affiner son choix, fonctionnalité par fonctionnalité.

Dans cette section, nous nous pencherons sur WS3, un modèle qui va plus loin que le celui de Richardson en adressant les APIs Semantic REST.

Ce modèle dissocie trois aspects d’une API : sa conception, son profile et sa sémantique.

Conception (Design dimension)

L’axe conception est proche du modèle de maturité de Richardson. Il évalue les caractéristiques structurelles et comportementales de l’interface de l’API et son niveau de conformité avec l’architecture REST.

Le niveau RPC est le niveau 0, il n’implique aucune contrainte.

Pour atteindre le niveau Resources, les services de l’API doivent être organisés en ressources auxquelles sont attachées les opérations. Les communications doivent être stateless, les ressources manipulées au moyen de leur représentation et les messages doivent être auto-décrits.

Le niveau suivant, Protocol Compliance, implique que l’API utilise et respecte les caractéristiques du protocole HTTP, notamment le caractère idempotent ou non des verbes.

Atomic Resources, le niveau 4, ne peut être atteint que si la plus petite unité de données qui peut être traitée par les opérations est la ressource. C’est à dire que si on a une ressource utilisateur, il n’est pas possible d’avoir une opération pour modifier l’adresse email et une autre pour modifier l’adresse postale. Soit email et adresse deviennent des ressources, soit une seule opération peut exister, modifiant toute la ressource utilisateur. Cela force le CRUD.

Profile (Profile dimension)

L’axe profile reflète la richesse de la documentation qui est envoyée dans les réponses des APIs. Ici, le sens de profile utilisé est celui décrit dans la RFC 6906. Le modèle ne considère que les profiles qui peuvent être interprétés par des agents logiciels. Pour cela, ils doivent respecter une structure et des mots-clés qui permettront à des algorithmes de les parcourir. Ainsi, les auteurs de ce modèle disent que “cette contrainte renforce le principe selon lequel la documentation doit être utilisée uniquement pour guider les clients au moment de l'exécution, au lieu de guider le développeur (c'est-à-dire un humain) au moment de la conception.”

Pour atteindre le niveau Interaction Profile, une API doit décrire plusieurs choses. Tout d’abord la sémantique (pour l’humain) du protocole de communication adopté. Mais aussi, toutes les opérations et les informations permettant de les exécuter, comme la méthode HTTP, l’URI, les media-types supportés, les attributs obligatoires, etc. Tout cela correspond à la description fonctionnelle de l’API.

Le niveau supérieur, Domain Profile, impose que le domaine d’application de l’API soit décrit. Cela inclut l’ordre dans lequel exécuter les opérations, les conditions qui rendent une opération disponible et le résultat qu’elle produit (par exemple l’envoi d’un email), etc.

Ce dernier niveau peut être atteint de trois manières : (i) utilisant des hyperliens vers d’autres ressources (hypermedia), (ii) grâce aux headers du protocole de communication utilisé, souvent HTTP, ou (iii) en documentant l’API.

Sémantique (Semantic Dimension)

Dans cette dimension, les auteurs parlent de sémantique interprétable par la machine, comme nous l’avons abordé dans les précédents articles de cette série.

Le niveau Semantic Description implique que toutes les propriétés et opérations d’une ressource sont sémantiquement décrites.

Au-delà, le niveau Linked Data est atteint lorsque l’API décrit sémantiquement les liens entre les ressources. Lorsque l’on souhaite atteindre ce niveau, la mise en place simultanée de l’hypermedia est un choix cohérent.

Comparaison des technologies d’APIs Semantic REST

Aucune technologie unique ne permet de développer des APIs Semantic REST qui atteignent le plus haut niveau de maturité de WS3. Dans la majorité des cas, il vous sera nécessaire d'implémenter par vous-même des fonctionnalités manquantes.

C’est pourquoi nous avons inclus dans cette comparaison des technologies qui ne proposent aucune fonctionnalité dans certaines catégories, ou même axe de WS3. Toutefois, selon votre besoin, elles peuvent tout de même vous être utiles.

Pour comparer ces technologies, nous avons élaboré des critères qui soulignent leurs différences fonctionnelles et d’approche. Pour chaque catégorie du modèle WS3, plusieurs critères sont déclinés. Cela vient en réponse au fait qu’il existe plusieurs solutions techniques pour atteindre un même niveau. Or, lors du choix des technologies qui seront utilisées pour implémenter l’API, il est nécessaire d’identifier précisément ces différences techniques.

Nous avons décrit plus en détail la méthodologie qui nous a permis d'élaborer ces tableaux de comparaison, ici.

Formats de message (ou Data Interchange Formats)

Vous trouverez ci-dessous un tableau comparant les data interchange formats existants pour faciliter la création d’APIs Semantic REST.

Ce tableau est plus complet que celui présenté dans notre article sur l’hypermedia car il contient des technologies du Web Sémantique. Il compare les technologies :  HAL, Collection+JSON, Siren, Uber, Mason, Json:Api, Atom, Turtle, RDF XML, OData et JSON-LD (à combiner avec Hydra).

Langages de description d’interfaces

Vous trouverez ci-dessous un tableau comparant les langages de description d’interfaces existants pour faciliter la création d’APIs Semantic REST.

Ce tableau compare les technologies : Rapido, Modeling RESTful Applications, Formal modeling of RESTful APIs using finite state machines, A model-driven approach for REST compliant service, Hydra, Atom Publishing Protocol + Atom Syndication Format, WSDL + SAWSDL, WADL, OpenAPI/Swagger, API Blueprint + MSON, hREST + microWSMO, RESTdesc, RADL, RAML et I/O Docs.

Frameworks

Vous trouverez ci-dessous un tableau comparant les frameworks existants pour faciliter la création d’APIs Semantic REST.

Ce tableau compare les technologies : Restfulie (ruby), Restfulie (.NET), Restfulie (java), API Platform, Spring HATEOAS, JAX-RS 2.0, A framework for the semantic description of restful web apis et Ripozo.

Morice : choisir les technologies pour faire une API Semantic REST en un clin d’œil

Pour simplifier le choix des technologies qui vous permettront de créer vos APIs Semantic REST, ou seulement Semantic, ou seulement REST, nous avons développé et mis en ligne un assistant.

Sur ce dernier, choisissez le type de technologies que vous recherchez et cochez les critères qui doivent être nativement supportés par la technologie. Enfin, attribuez un poids à chaque critère pour représenter l’intérêt qu’il a pour vous. Ce poids sera utilisé pour calculer un score à chaque technologie. Ce dernier sera utilisé pour ordonner la liste des résultats.

Vous pouvez retrouver l’outil à cette adresse.

INCLURE CETTE VIDEO

Conclusion

Vous voilà désormais équipé d’un modèle de maturité, de tableaux et d’un outil pour vous aider à choisir les fonctionnalités que vous inclurez dans vos futures APIs, ainsi que les technologies qui vous aideront à les développer.

Les tableaux l’illustrent bien : les technologies sont très différentes et encore peu matures quand l’objectif est de développer des API Semantic REST qui atteignent les plus hauts niveaux de WS3.

Notre bilan face à ces APIs Semantic REST est donc le suivant : il s’agit encore d’un sujet de recherche passionnant et prometteur, dont l’industrialisation est à faire.

La semaine prochaine, nous clôturerons cette série en vous partageant notre vision des étapes à suivre pour industrialiser ce sujet.