Consommer une API en JavaScript : méthode fiable avec gestion des erreurs

Une API permet à une page web de récupérer ou d’envoyer des données à un autre service. En JavaScript, la fonction fetch() suffit souvent pour effectuer cet échange, mais une requête qui fonctionne dans le cas idéal ne constitue pas encore une intégration fiable. Il faut aussi vérifier le statut HTTP, anticiper une réponse mal formée, informer l’utilisateur et éviter qu’une requête lente ne bloque l’interface.

La méthode ci-dessous convient à un projet front-end sans bibliothèque supplémentaire. Elle explique le déroulement d’une requête, la lecture d’une réponse JSON et les contrôles à ajouter avant de considérer l’appel comme réussi.

Ce qui se passe réellement entre votre page et l’API

Un appel à une API suit plusieurs étapes distinctes. Le navigateur envoie une requête vers une URL, le serveur traite cette demande puis renvoie une réponse composée notamment d’un statut HTTP, d’en-têtes et, souvent, d’un corps contenant des données JSON.

Avec fetch(), JavaScript retourne une promesse. Cette promesse est résolue lorsque le navigateur reçoit une réponse du serveur. Point important : une réponse HTTP 404 ou 500 ne fait généralement pas échouer la promesse. Pour fetch, la communication a bien abouti, même si le serveur indique que la ressource est introuvable ou qu’il rencontre un problème.

C’est pourquoi il faut distinguer deux familles d’erreurs :

• Les erreurs réseau : serveur inaccessible, problème de connexion, requête bloquée ou domaine non autorisé par la politique CORS.
• Les erreurs HTTP : réponse 400, 401, 403, 404, 429 ou 500, par exemple.

Une intégration correcte traite ces deux situations séparément au lieu de placer tout le contrôle dans un simple bloc catch.

Construire une requête fetch lisible

Pour une requête GET simple, l’appel minimal consiste à transmettre l’URL à fetch. La fonction renvoie une promesse représentant la réponse future. Avec la syntaxe async/await, le déroulement est plus facile à lire : on attend d’abord la réponse, puis on demande au navigateur de convertir son contenu en JSON.

La logique générale est la suivante : appeler fetch avec l’URL, stocker l’objet Response, vérifier son statut, puis exécuter response.json(). La conversion JSON est elle-même asynchrone et peut échouer si le serveur renvoie une page HTML, un contenu vide ou un document qui ne respecte pas le format annoncé.

Ne mélangez pas ces deux opérations. La variable obtenue après fetch ne contient pas encore directement les données métier. Elle contient une réponse avec des propriétés comme status, ok, headers et des méthodes permettant de lire le corps.

Pourquoi vérifier response.ok

La propriété response.ok vaut true lorsque le statut HTTP se situe dans la plage des réponses réussies. Si elle vaut false, votre code doit interrompre le traitement normal et afficher ou transmettre une erreur adaptée.

Une vérification explicite évite une erreur fréquente : tenter d’utiliser des données comme si elles étaient valides après une réponse 404. Selon l’API, cette réponse peut contenir un objet d’erreur différent du format attendu par votre interface.

Le statut exact reste utile pour affiner le diagnostic. Une réponse 401 indique généralement qu’une authentification est nécessaire, tandis qu’une réponse 403 signale un accès refusé. Une réponse 429 peut traduire une limitation du nombre de requêtes. Le message affiché à l’utilisateur ne doit pas forcément reprendre le détail technique, mais celui-ci doit être conservé dans les journaux de développement.

Lire et contrôler les données JSON reçues

Après la vérification du statut, convertissez la réponse avec response.json(). Cette étape ne garantit pas que les données correspondent à ce que votre application attend. Un serveur peut renvoyer un objet alors que votre interface attend un tableau, ou modifier un champ à la suite d’une évolution de l’API.

Avant de parcourir une liste, contrôlez donc sa forme. Si votre code attend un tableau de produits, vérifiez que la valeur reçue est bien un tableau. Si vous avez besoin d’un champ précis, vérifiez également sa présence avant de l’afficher. Ces contrôles sont particulièrement utiles lorsque l’API est externe ou lorsqu’elle est susceptible de renvoyer des réponses différentes selon les paramètres.

Une validation simple côté client ne remplace pas une validation côté serveur. Elle sert à éviter une interface cassée et à produire un message compréhensible. Pour des données sensibles, des permissions ou une opération d’écriture, le serveur reste l’autorité qui doit contrôler la validité de la demande.

Ne faites pas confiance au seul en-tête Content-Type

L’en-tête Content-Type indique le format annoncé par le serveur, mais il ne suffit pas à prouver que le contenu est correctement formé. Vous pouvez le consulter pour produire un diagnostic, puis gérer l’échec éventuel de la conversion JSON.

Une API indisponible peut par exemple renvoyer une page d’erreur générée par un proxy. Si votre code appelle directement response.json() sans prévoir cette possibilité, l’utilisateur recevra une erreur technique difficile à comprendre.

Gérer les erreurs sans masquer leur cause

Le bloc try…catch est adapté à une fonction qui réalise une requête complète. Le bloc try regroupe l’appel, la vérification du statut et la lecture du JSON. Dans catch, vous pouvez distinguer une erreur réseau d’une erreur applicative créée par votre propre code.

Pour conserver cette distinction, créez un message interne suffisamment précis avant de le traduire en message d’interface. Un utilisateur peut voir « Les données ne sont pas disponibles pour le moment », tandis que la console ou votre système de suivi conserve le statut HTTP, l’URL concernée et l’erreur originale.

• Pour une erreur réseau, proposez de vérifier la connexion ou de réessayer plus tard.
• Pour une réponse 401 ou 403, vérifiez la session et les droits d’accès.
• Pour une réponse 404, contrôlez l’identifiant ou l’URL demandée.
• Pour une réponse 429, évitez les tentatives immédiates répétées et respectez les indications du serveur.
• Pour une réponse 5xx, considérez que le problème vient probablement du service distant et prévoyez une solution de repli.

Évitez toutefois d’afficher le texte brut renvoyé par une API sans le traiter. Il peut contenir des informations internes ou un format destiné aux développeurs, pas au public.

Éviter les requêtes lentes avec AbortController

Une requête réseau peut durer plus longtemps que prévu. Sans limite, l’interface peut conserver un indicateur de chargement alors que l’utilisateur a déjà changé de page ou de recherche. AbortController permet d’annuler une requête lorsque le délai est dépassé ou lorsqu’elle n’est plus pertinente.

Le contrôleur est créé avant l’appel à fetch, puis son signal est transmis dans les options de la requête. Une minuterie peut ensuite déclencher l’annulation après un délai défini par votre application. Dans le catch, vérifiez si l’erreur correspond à une annulation volontaire afin de ne pas afficher un message d’échec lorsque l’utilisateur a simplement lancé une nouvelle recherche.

Cette technique est particulièrement utile pour un champ de recherche. Si une requête part à chaque saisie, annulez la précédente dès qu’une nouvelle valeur est envoyée. Vous évitez ainsi que les réponses arrivent dans le désordre et qu’un résultat ancien remplace le résultat le plus récent.

Afficher un état de chargement cohérent

Une intégration API ne se limite pas à la récupération des données. L’interface doit indiquer les trois états principaux : chargement, réussite et échec. Le message de chargement doit apparaître avant l’appel, puis disparaître dans tous les cas, y compris lorsqu’une erreur survient.

Une structure de contrôle claire évite de laisser un bouton désactivé ou un indicateur visible après une exception. Dans une fonction asynchrone, utilisez une partie de nettoyage exécutée après la réussite comme après l’échec. Selon votre code, ce nettoyage peut réactiver un bouton, retirer un message de chargement ou restaurer une action accessible au clavier.

Ne remplacez pas automatiquement toute la page par un message d’erreur. Conservez les informations déjà affichées lorsqu’elles restent valides et indiquez précisément quelle action a échoué. Pour une mise à jour secondaire, une notification discrète peut être préférable à un écran vide.

Ajouter les options nécessaires pour les autres méthodes

Une requête GET peut souvent être réalisée sans options supplémentaires. Pour envoyer des données, vous devez préciser la méthode HTTP, les en-têtes et le corps de la requête. Avec un contenu JSON, l’en-tête Content-Type: application/json doit correspondre à la conversion du contenu en chaîne JSON.

Ne placez jamais directement une valeur saisie par l’utilisateur dans une URL ou un corps de requête sans appliquer les règles attendues par l’API. Côté serveur, les données doivent être validées, les droits contrôlés et les opérations sensibles protégées contre les requêtes forgées. Côté navigateur, l’objectif est surtout de transmettre des données correctement structurées et de traiter la réponse sans exposer de secret.

Une clé privée ne doit pas être intégrée dans le JavaScript livré au navigateur. Tout élément envoyé au client peut être consulté par l’utilisateur. Lorsqu’un service exige un secret, faites généralement passer l’appel par un serveur que vous contrôlez, avec des règles d’accès et une gestion adaptée des secrets.

La checklist d’un appel API prêt pour la production

Avant de considérer votre intégration comme terminée, vérifiez les points suivants :

1. L’URL et les paramètres sont construits à partir de valeurs maîtrisées.
2. Les erreurs réseau et les statuts HTTP sont traités séparément.
3. La réponse est convertie dans le format attendu, sans supposer que le JSON est toujours valide.
4. Les champs indispensables sont contrôlés avant leur affichage.
5. L’utilisateur voit clairement le chargement, la réussite et l’échec.
6. Une requête obsolète ou trop longue peut être annulée lorsque le contexte le justifie.
7. Aucun secret privé n’est exposé dans le code JavaScript envoyé au navigateur.
8. Les tests couvrent au moins une réponse réussie, une absence de résultat, une erreur HTTP et une coupure réseau.

Pour progresser, commencez par une requête GET simple dans un environnement de test, puis ajoutez les contrôles un par un. Cette progression permet d’identifier rapidement si le problème vient de l’URL, du statut HTTP, du format des données ou de l’affichage. Une API bien intégrée n’est pas celle qui répond uniquement quand tout se passe bien : c’est celle qui reste compréhensible et maîtrisable lorsque le réseau, le serveur ou les données ne se comportent pas comme prévu.