Dans un monde où les architectures microservices sont de plus en plus importantes, prisées et recherchées de tous, l’API est au centre de toutes les discussions. On ne compte plus le nombre de clients qui nous parlent d’APIsation de leurs applications legacy, et je pense qu’il ne sert à rien d’essayer de rattraper le compte.

Seulement, les APIs, ce n’est pas à prendre à la légère pour autant. Si leur nombre est aussi inestimable que leur utilité, le nombre d’APIs non spécifiées, non testées, difficiles à maintenir pour les nouveaux développeurs ET à comprendre pour les utilisateurs finaux ne peut pas vraiment être estimé non plus.

Je ne parle bien évidemment ici pas de documentation technique, de commentaires de code ou de README dans les fichiers des projets, je parle de spécification à destination des personnes désireuses de savoir ce que l’API peut faire pour eux, pas comment.

De nombreuses spécifications ont vues le jour au fil des années, les plus connues étant OpenAPI et Swagger.

Qu’est-ce que Swagger et OpenAPI

(Les deux projets présentent des différences, mais le principe reste pour nous aujourd’hui le même. Le but n’étant pas de comparer les deux projets, je n’entrerai pas dans le détail de leurs différences.)

Swagger et OpenAPI sont des projets de spécification d’API. Leur fonctionnement est similaire :

  • Un format de fichiers permettant la spécification fonctionnelle de l’API
  • Des outils pour générer, aider à la réalisation du mocking et des tests de l’API dans le langage souhaité (quasiment tous les langages “mainstream” sont représentés)
  • Des outils pour générer le code des clients qui manipuleront l’API, comme par exemple des scripts Shell, des librairies Java ou NodeJS, PHP ou Python, etc…

Attardons-nous un peu sur le contenu des fichiers permettant la spécification de l’API. Ces fichiers sont la source du pouvoir, c’est en leur sein que sont définies les routes de l’API, les paramètres qu’elles acceptent, le format de leur retour, les types de données et bien plus. Ces fichiers peuvent soit être créés / édités à la main, étant souvent au format JSON ou YAML, soit créés à l’aide des outils graphiques mis à disposition.

Ce sont ces fichiers qui, une fois terminé, permettront à l’API de savoir comment traiter ses requêtes, mais également de valider les données à l’entrée (oui on parle bien ici de validation automatique, de rien), mais également de générer la documentation fonctionnelle de l’API (spécification), au format d’une page web (ou autre) reprenant tous les points d’entrée de l’API avec les données qu’ils acceptent, des exemples de retour et même des formulaires pour directement les tester !

J’insiste sur le fait que cette spécification est extrêmement utile pour les clients finaux de l’API, mais qu’elle ne s’adresse pas qu’aux clients de l’API. Elle s’adresse également à l’équipe elle-même, aux nouveaux développeurs, afin de comprendre l’API, mais également aux anciens, pour se rappeler de son fonctionnement.

Générer ses APIs

Que ce soit avec un projet ou l’autre, le principe est le même :

Dans un premier temps, la réalisation des fichiers de spécification est nécessaire, que ce soit à la main ou avec les outils mis à disposition par les deux projets

Pour ce qui est du code de l’API elle-même, il vous faudra utiliser les outils mis à disposition par les projets. Ces outils vont lire les fichiers de spécification réalisés précédemment pour générer le code de votre API dans le langage désiré. La majorité des langages sont représentés par les deux outils, alors faites votre choix ! Notons que si les partie serveur (dans certains langages), routage et services sont générées, la partie service (business) est quant à elle vide de logique. Restera bien évidemment à votre charge de remplir la logique métier de votre application.

Pour ce qui est du code des clients (donc qui vont requêter l’API), là encore il faudra utiliser les outils mis à votre disposition par les projets. Là encore, une grande liste de clients sont supportés pour tous les langages courants, donc pas de soucis de ce côté-là.

Autres points d’intérêt

Il est à noter que si nous avons dans ce document essentiellement discuté de la génération des APIs et de leurs clients, les outils proposés par ces projets vont plus loin. Génération de documentation, mocking, design (de l’API, pas des interfaces graphiques), adopter l’une de ces spécifications n’est pas qu’une question d’accélération du développement pur.

Conclusion

Une API mal documentée impacte les développeurs, mais une API non spécifiée, n’ayant pas de documentation purement fonctionnelle à destination des utilisateurs finaux, c’est une autre paire de manches. Des outils sont aujourd’hui à notre disposition pour éviter ces aberrations, et nous avons dans ce document à peine effleuré la surface de leurs possibilités.

Pourquoi ne pas leurs donner une chance ?

©️ Julien PONTILLO | Consultant KLANIK