🍪🧬 Créer une API Web simplement et rapidement
Temps de lecture : 8 minutes
Hello les petits Biscuits, bonne année 2026 à vous ! 🥳
Bienvenue sur la 41ème édition de Ruby Biscuit.
Vous êtes maintenant 612 abonnés 🥳
Bonne lecture.
Créer une API Web simplement et rapidement
Ce mois-ci, nous allons plonger dans la création d’une API. Bien structurer son API est crucial pour votre application. Découvrez des techniques qui peuvent améliorer la maintenabilité et les performances de vos projets.
Partie théorique
Avant de nous lancer, faisons un bref rappel sur les APIs et leurs rôles dans une application web.
Une API web va exposer vos données à l’extérieur de l’application. Elle va permettre aussi de communiquer avec d’autres services web.
Il est considéré comme une bonne pratique de :
versionner vos API,
protéger leurs accès (authentification et doorkeeper),
paginer leurs réponses (pagy),
avoir une documentation (Rswag),
respecter le format JSON Api et les formats ISO (jsonapi-serilizer).
Setup
Après ce bref rappel, passons à l’implémentation.
Tout d’abord, voici les gems que nous allons utiliser tout au long de cet article.
Dans cet article, je n’aborde pas l’authentification. Il existe plusieurs façons de la gérer, et cela pourrait faire l’objet d’un article à part. Il ne faut cependant pas l’oublier, sous peine d’exposer vos données à n’importe qui.
Nous allons maintenant créer un controleur parent pour les futurs contrôleurs d’API de l’application.
Il existe deux écoles pour nommer un contrôleur parent dans un namespace : BaseController ou ApplicationController. Ici, nous allons ici choisir ApplicationController.
Ensuite, je vais paginer mes ressources avec la gem Pagy. Par défaut, je choisis de renvoyer 50 ressources par appel API. On pourrait laisser aux utilisateurs la possibilité de changer cette valeur dans la payload, mais par soucis de simplicité on ne va pas le faire ici.
Implémentation pour le modèle Project
Comme dans de nombreuses applications web, nous avons un modèle Project. Commençons par créer un index pour les projets dans l’API.
Il faut donc ajouter une route dans le namespace api, puis dans le namespace v1.
Contrôleur Projects
Nous allons maintenant créer le contrôleur Projects.
Nous appliquons d’abord la pagination grâce à la méthode pagy() fournie par la gem. Elle reçoit comme premier argument nos ressources, puis la valeur de pagination.
Ensuite nous allons renvoyer un json qui contient nos données, des liens vers les pages (links) et quelques metadonnées conformément à la spec JSON API.
Serializer
Pour respecter le principe de responsabilité unique, nous générons donc le hash dans un Serializer avec la gem jsonapi-serializer. Sa mission est de transformer la donnée brute en un format clair et lisible. La gem va aussi respecter les spécifications de JSON API.
Format des données en général et des dates en particulier (avec le serializer)
Respectez la norme OpenAPI pour le format des données. Notamment pour les dates utilisez la méthode iso8601 .
Par exemple, le 13 mai 2025 devra s’écrire "2025-05-13" ou "2025-05-13T14:45:00+02:00".
Rendu
Voici un exemple d’un résultat d’une requête faite avec Postman sur l’endpoint http://localhost:3000/api/v1/projects (en changeant la pagination à 2)
Optimisation : Requête N+1
Attention aux requêtes N+1 dans vos contrôleurs !
Si votre Serializer utilise des données provenant d’autres tables, pensez à les inclure.
Tests
Assurez-vous de la fiabilité de votre code grâce à des tests.
Dans notre cas, nous allons écrire deux tests :
un test du
ProjectSerializer,un test de requêtes sur l’API.
Dans un premier temps, nous testons que le Serializer renvoie les bonnes données.
Pour le test d’API et la document nous allons utiliser Swagger mais nous verrons cela dans un prochain article
Conclusion
Et voilà, vous venez de construire une API simplement et rapidement.
Bonne année 2026 !
— Alexandre