Préparez-vous à concevoir votre propre API REST
Maintenant que vous avez vu comment utiliser une API externe, parlons davantage de quand et comment construire concrètement une API REST vous-même.
Pourquoi aurais-je besoin de construire ma propre API REST ? Je ne peux pas utiliser l’une de ces milliers d’API qui existent et dont tu nous as parlé dans la dernière partie ? 🤔
Il existe deux raisons principales pour lesquelles vous pourriez vouloir développer votre propre API :
Si vous construisez votre propre application web ou mobile, par exemple pour des recettes de cuisine, où vous savez que vous devrez sauvegarder et manipuler beaucoup de données. 🍳 Vous auriez absolument besoin d’une base de données, mais il n’est pas souhaitable que les développeurs front-end aient besoin de connaître SQL pour pouvoir afficher les informations sur votre UI. Vous voulez aussi respecter les normes pour les applications web pour qu’il y ait une couche API entre votre base de données et l’accès à vos données. Vous ne voulez pas que n’importe quel développeur soit en capacité d’accéder directement à votre base de données, pour des questions de sécurité et de confidentialité. Et vous voulez une manière rapide et efficace de rechercher et requêter les données existantes. Pour ce faire, vous aurez besoin d’une API interne.
Si vous construisez une application web ou mobile où vous voulez que d’autres développeurs soient en capacité d’interagir avec vos données. Par exemple, une application où vous collectez des données sur les personnages de votre série télé favorite et où vous voulez que d’autres développeurs puissent ajouter et utiliser des données.
Lancez-vous dans la conception de votre API
Comme pour toute chose un peu compliquée, un design réfléchi et structuré est essentiel pour obtenir un succès sur le long terme. C’est peut-être facile de commencer par tout construire tout de suite en fonçant tête baissée, mais avant de vous ruer sur votre clavier, vous devez réfléchir aux concepts de design-clés qui rendront votre API plus agréable d’utilisation et plus facile à scaler.
OK allons-y. Par quoi commence-t-on ? 🤔
Allons-y étape par étape. Commencez d'abord par vous poser des questions sur les fonctionnalités importantes dont vous avez besoin pour votre API :
De quel type d’endpoints avez-vous besoin ?
Quelles ressources devez-vous créer ?
De quelles ressources avez-vous besoin pour y effectuer les opérations CRUD ?
Avez-vous besoin des quatre opérations CRUD pour chaque ressource ? Ou seulement d’une ou deux ?
Une fois que vous aurez répondu à ces questions, vous serez prêt à commencer à préparer … votre documentation.
Documentez toute la journée : découvrez pourquoi une documentation adaptée est essentielle
Attends, on n'est pas censé créer une API ? Pourquoi est-ce que la documentation arrive tout de suite, on peut la faire à la fin non ? 🙄
Non, non, non ! Lors des chapitres précédents nous avons dû consulter la documentation GitHub afin de pouvoir utiliser l’API comme il se doit. Sans toutes les informations de la documentation, nous aurions eu du mal à avoir le bon endpoint ou savoir quels paramètres préciser... La documentation est une des partie les plus importantes des API ! Quand vous créez une API, vous devez également tenir compte des autres développeurs qui utilisent votre API. Cela implique d’avoir une bonne documentation pour qu’ils puissent facilement comprendre ce que votre API peut accomplir et comment l’utiliser.
Comme vous l’avez vu avec la documentation GitHub, de nombreuses informations doivent être expliquées à votre utilisateur API. Elles incluent :
Les descriptions des ressources API.
Les URI et verbes HTTP disponibles ainsi que leur fonction.
Les paramètres (s’il y en a) qui doivent être donnés à l’endpoint.
Un exemple de requête.
Une réponse typique pour la requête donnée.
Chaque API organise la documentation de manière légèrement différente, mais voici quelques bons exemples pour vous aider.
Documentation de l’API Stripe
Dans l’API de Stripe vous pouvez clairement voir que la documentation décrit l’URL de la ressource et les informations pertinentes que les développeurs doivent pouvoir comprendre.
La documentation montre également un exemple de réponse aux requêtes API :
Documentation de l’API Pinterest
L’API Pinterest contient un bon exemple d’affichage d’un verbe HTTP, d’un URI, de paramètres, et d’une description de la fonction de l’endpoint.
La documentation donne de nombreuses informations sur les endpoints et les requêtes, mais elle se doit aussi de documenter la gestion des erreurs.
Gérez les erreurs 🙅♀️
Comme nous l’avons vu dans les chapitres précédents, une requête peut être un succès mais aussi un échec, et ce pour diverses raisons : ressource introuvable, serveur indisponible… Votre API doit avoir une bonne gestion des erreurs. Si un développeur essaye accidentellement d’utiliser votre API pour un usage non souhaité (authentification incorrecte, lettres inutiles ajoutées à une requête), votre API doit être capable de dire à l’utilisateur quelle a été son erreur pour qu’il puisse la corriger. Et oui, personne n’est à l’abri d’une faute de frappe ! Le code HTTP donne une information sur le type d’erreur mais est généralement accompagné d’un message d’erreur dans le body de réponse.
Vous avez vu à quoi ressemblaient certaines erreurs dans l’API GitHub lorsque nous avons voulu créer un repository dans la dernière partie. Souvenez-vous, quand nous avons essayé d’effectuer une requête sans notre token d’authentification, nous avons reçu la réponse suivante :
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3/repos/#edit"
}
C’est ainsi que grâce au message d’erreur nous avons su que nous avions oublié notre code d’authentification ! Il existe de nombreux types d’erreurs différents pouvant se produire dans votre API qui, si elles sont gérées correctement, peuvent faciliter la vie des développeurs lorsqu’ils utilisent votre API. 💪
L’API de Meetup contient un bon exemple de toutes les erreurs différentes qui peuvent se produire quand vous utilisez leur API et ce qu’elles signifient :
Toutes les erreurs possibles de l’API Meetup
announce_error | Erreur dans l’annonce d’un événement |
description_error | Désolé, votre description Meetup est trop longue |
duration_error | La durée de cet événement n’est pas valide. |
event_error | L’ID fourni ne correspond pas à un évènement pouvant être modifié |
event_hosts_error | Un ou plusieurs des membres donnés ne sont pas des membres actifs de ce groupe |
featured_photo_id_error | Il y a un problème avec la photo fournie. |
fee.amount_error | Si le groupe se trouve aux États-Unis, le montant à acquitter ne peut pas excéder 4999. Sinon, il ne peut pas excéder 1 000 000. |
fee.refund_policy_error | La politique de remboursement de fonds ne peut pas excéder 250. |
guest_limit_error | Le nombre d’invités maximum n’est pas valide. |
how_to_find_us_error | Votre description « Comment nous retrouver » est trop longue. |
Une partie nécessaire et importante lors de la conception de votre API est la réflexion sur les possibilités de mauvaise utilisation par les utilisateurs ! Ainsi en fonction de l’erreur, vous pouvez renvoyer le message approprié dans la réponse.
En résumé
Vous pouvez construire une API soit pour l’utiliser dans votre propre application, soit pour que d’autres développeurs puissent interagir avec vos données.
Il est important en concevant une API de penser à toutes les fonctionnalités nécessaires avant de commencer à la développer.
La documentation et une bonne gestion des erreurs sont importantes pour que d’autres développeurs puissent comprendre votre API.
Maintenant que vous avez les bases, concevez les endpoints de votre API. OK, mais comment faire ? Voyons cela ensemble dans le chapitre suivant.
