useApi : appelez vos webservices avec un hook React
Découvrez comment appeler vos webservices React de façon élégante et customisable.
Avec la sortie de React 16.8 en Février 2019, les Hooks nous ont donné la possibilité de créer nos propres comportements, entièrement adaptable à nos besoins. Si vous utilisez régulièrement des webservices dans vos projets, vous avez du être confronté à la difficulté d’architecturer correctement vos appels afin d’éviter la répétition de code et d’avoir quelque chose de correctement intégré dans votre environnement.
Je vous propose ici ce que j’utilise dans mes projets. Ce hook est entièrement customisable selon vos besoins et s’intègre parfaitement dans votre environnement. Il gère les erreurs, les callbacks, les chargements, les headers, les différents types de résultats, etc. Il utilise par défaut Axios mais vous pouvez utiliser la méthode de votre choix. Vous découvrirez comment l’utiliser et comment il fonctionne.
Voilà à quoi il ressemble :
Dans votre projet, il vous suffit de l’enregistrer dans un fichier useApi.hook.js par exemple et de l’appeler quand vous souhaitez l’utiliser grâce à import { useApi } from “./api.hook.js”;.
Comment l’utiliser ?
L’utilisation se veut extrêmement simple. L’URL de l’API est renseignée en valeur par défaut des paramètres d’entrée de callApiWithAxios. Vous pouvez la surcharger si vous appelez différents webservices au sein de votre application grâce au paramètre apiUrl.
Un GET
Il suffit de passer dans l’objet params le namespace. Le résultat de l’appel se trouvera dans la clé data, ici avec un alias people. On demande également que la clé data soit initialisée à un tableau vide grâce au paramètre defaultValue. Et bien évidemment on a accès aux clés isLoading et error.
Un POST
Un POST est évidemment légèrement plus complexe. Il faut dans un premier temps initialiser le hook car un hook ne peut être conditionné.
Il suffit ensuite d’appeler setParams de la même manière que pour un get mais avec certains paramètres supplémentaires, et surtout au bon moment.
Voici par exemple un formulaire qui enverra son contenu à sa soumission (avec en bonus, un petit message indiquant le chargement !) :
Et les autres méthodes ?
Toutes les autres méthodes sont utilisables de la même façon qu’un POST.
Des callbacks ?
Dans le formulaire précédent, vous avez vu deux paramètres : callbackSuccess et callbackFail. Comme leur nom l’indique, ces deux paramètres prennent un callback qui sera exécuté en cas de succès ou d’échec de l’appel. Il propose en paramètre les données ou l’erreur de l’appel selon le cas.
Et si je veux transformer les données reçues ?
Dans de nombreux cas il est utile de pouvoir transformer les données reçues afin d’éviter de les stocker en double. Par exemple dans le cas d’un tableau avec des filtres ou pour un formulaire d’édition. Ce cas est prévu. useApi, en plus de renvoyer les données dans la clé data, renvoie une méthode de mise à jour (un setter) à travers setData, toujours renommable grâce à un alias.
Je veux appeler plusieurs webservices.
Comme je l’expliquais en introduction. Vous pouvez indiquer directement dans le hook custom le chemin de votre API par défaut. Cependant, si vous appelez différents webservices dans votre application, vous pouvez surcharger cette clé au moment de l’appel avec la clé apiUrl dans params :
Pourquoi utiliser un hook et pas une simple méthode pure ?
L’intérêt d’utiliser un hook est de pouvoir l’intégrer parfaitement dans le reste de votre application. Dans mes projets, j’ai par exemple connecté ce hook au contexte en ajoutant un identifiant unique pour chaque appel, stocké dans un set. Un composant Spinner écoute ce set présent dans le context et s’affiche en pleine pages dès qu’il y a quelque chose dedans. Cela me permet de gérer très rapidement un affichage clair quand un appel est fait avant de gérer par composant un état de chargement.
Explication du hook
L’appel à vos webservices
Les appels se font via la méthode callApiWithAxios. Cette méthode gère l’appel, un identifiant, les différents verbes, la transformation des données en sortie, etc. Si vous ne souhaitez pas l’utiliser, vous pouvez passer une méthode au paramètre callApi. Il faut cependant répondre à des exigences : prendre les mêmes paramètres en entrée et en sortie.
L’entrée est un objet avec les paramètres :
- method qui a pour valeur par défaut “get”. Ce paramètre sert à indiquer comment vous allez appeler votre API. Par exemple en get, post, delete, put, etc
- Le namespace correspond au chemin où se trouve votre ressource. Par exemple, si je souhaite accéder à la ressources “/people”, il me suffit d’indiquer “people”.
- L’id permet de spécifier un identifiant spécifique de ressource. Par exemple si je souhaite accéder en get à un people en particulier, il me suffit de spécifier son id.
- Dans de nombreux cas, vous devez ajouter des données à votre requête. Ces données sont à passer au paramètre payload.
- Parfois, vous devrez ajouter des headers à votre requête, comme lorsque vous envoyez des fichiers par exemple. Les headers sont surchargeables grâce au paramètre headers.
En sortie de cette méthode, nous avons également accès à un objet où ce qui nous intéresse vraiment se trouve dans l’attribut data.
Dans la méthode callApiWithAxios vous pouvez modifier la constante apiUrl afin d’appeler votre webservice. Bien évidemment, vous pouvez modifier la déclaration de cette constante pour la sortir dans un fichier de config en json ou même rendre cette variable dynamique lors de vos builds par exemple.
Le custom Hook
Il est assez simple et basique. Grâce à différents useState, on stocke les paramètres, les données, l’état de chargement et les erreurs.
Un useEffect permet de relancer l’appel quand les données ont été modifiées.
Un objet est retourné avec toutes les données utiles :
- data : pour récupérer les données en réponse à votre appel
- setData : pour modifier les données reçues
- setParams : pour modifier les paramètres de votre appel et l’exécuter quand vous le souhaitez
- isLoading : pour pouvoir afficher un loader sur votre composant pendant l’appel au web service
- error : pour gérer les erreurs potentielles (message d’erreur clair ? Résilience ?)
Conclusion
Vous pouvez trouver un projet d’exemple sur code sandbox.
Ce design se veut le plus modulable possible, n’hésitez pas à le modifier selon vos besoins ou me proposer vos améliorations (stockage du chemin de l’appel dans des fichiers de config ? Résilience ?, etc)
Un package npm viendra par la suite pour gérer les besoins génériques.
