API de récupération JavaScript expliquée

L'interface JavaScript Fetch propose une approche claire et intuitive pour exécuter des requêtes depuis votre application web, directement au sein du navigateur.

Elle se distingue par sa facilité d'utilisation et l'emploi d'une syntaxe JavaScript contemporaine. Cet article sert de guide pour exploiter efficacement l'API Fetch.

Qu'est-ce que l'API Fetch de JavaScript ?

L'API Fetch de JavaScript est une fonctionnalité intégrée aux navigateurs modernes, permettant d'effectuer des requêtes depuis le front-end. Elle constitue une alternative modernisée à la méthode AJAX XMLHttpRequest, plus ancienne.

Elle est accessible via une fonction globale nommée fetch. Lorsqu'elle est invoquée avec des paramètres, cette fonction retourne une promesse qui se résout avec une réponse. Grâce à fetch, il est possible de réaliser toutes sortes de requêtes HTTP.

Avantages de l'API Fetch comparée à d'autres méthodes

Elle offre une interface plus simple et intuitive, ce qui la rend facile à apprendre et à utiliser. L'utilisation de l'API Fetch se traduit par un code plus propre. À l'inverse, XMLHttpRequest est plus complexe et le code qui en découle est moins clair qu'avec l'API Fetch.
Elle supporte les promesses, ce qui permet d'écrire du code asynchrone de manière plus élégante. XMLHttpRequest ne les supporte pas, ce qui oblige à utiliser des rappels au niveau des gestionnaires d'événements. Selon vos préférences, vous pourriez préférer l'API Fetch.
Elle est intégrée nativement dans le navigateur, évitant ainsi l'ajout de bibliothèques supplémentaires pour effectuer des requêtes. L'ajout de bibliothèques alourdit votre bundle JavaScript et peut ralentir votre site web.

Comment utiliser l'API Fetch

Cette section abordera l'exécution de différentes requêtes à l'aide de l'API Fetch de JavaScript. Vous pouvez utiliser l'éditeur de code de votre choix, en veillant à ce que le code s'exécute dans le navigateur. Pour illustrer, je vais l'exécuter dans une balise script d'un fichier HTML.

Une requête GET simple

Commençons par apprendre à effectuer une requête GET simple. La structure du code est la suivante :

fetch(url)

Ainsi, pour récupérer les messages de l' API JSON Placeholder, il faut procéder ainsi :

fetch('https://jsonplaceholder.typicode.com/posts');

Cet appel de fonction renverra une promesse, qui se résoudra avec la réponse de l'API, ou générera une erreur en cas de problème. Pour accéder à la réponse, on utilisera donc le mot clé await. Cependant, await ne peut être utilisé que dans une fonction asynchrone.

Par conséquent, on enveloppera la fonction fetch dans une fonction asynchrone que l'on appellera ensuite. Si vous n'êtes pas familier avec ce concept, voici un guide détaillé sur le JavaScript asynchrone. Voici le code :

async function getData() {
        const response = await fetch('https://jsonplaceholder.typicode.com/posts');
        console.log(response);
    }

    getData();

Si vous exécutez ce code, vous obtiendrez le résultat suivant dans la console :

La sortie indique que fetch a retourné un objet Response. Cet objet contient des propriétés comme le statut, les entêtes, et le corps de la réponse. Les données sont stockées sous forme de chaîne JSON dans le corps. Nous devons donc extraire cette chaîne et analyser le JSON pour obtenir les données sous forme d'objet JavaScript.

Heureusement, l'objet Response possède une méthode pratique appelée json(). Cette méthode lit le corps de la réponse et tente d'analyser la chaîne au format JSON. Elle retourne une promesse qui se résoudra avec l'objet parsé à partir du JSON.

Cependant, cette méthode produira une erreur si le corps n'est pas une chaîne JSON valide. Par conséquent, nous devons analyser le JSON seulement si la réponse a un code de statut 200.

Ainsi, le code pour récupérer les messages sera le suivant :

async function getData() {
        const response = await fetch(
            "https://jsonplaceholder.typicode.com/posts"
        );

        if (response.status == 200) {
            const posts = await response.json();
            console.log(posts);
        } else {
            console.log("Une erreur s'est produite :", response.status);
        }
    }
    getData();

L'exécution de ce code donnera les résultats ci-dessous :

Il s'agit d'un tableau de 100 messages.

Certains points d'accès API nécessitent des en-têtes, qui peuvent servir à l'authentification par exemple. L'API Fetch de JavaScript facilite l'envoi d'en-têtes avec la requête. Vous devez ajouter un argument options à l'appel de fetch pour définir les en-têtes.

fetch(url, options);

Dans ce cas, l'exemple précédent devient :

async function getData() {
        const response = await fetch(
            "https://jsonplaceholder.typicode.com/posts", {
                 headers: {
                     'x-auth': '<your auth token>'
                 }
             }
        );

        if (response.status == 200) {
            const posts = await response.json();
            console.log(posts);
        } else {
            console.log("Une erreur s'est produite :", response.status);
        }
    }
    getData();

Étant donné que l'API JSONPlaceholder ne requiert pas d'en-tête d'authentification, ce code fonctionne de la même manière qu'avant. Il est cependant important de connaître la possibilité d'envoyer des en-têtes.

Ajouter d'autres options

En plus des en-têtes, vous pouvez passer de nombreuses autres options à la fonction fetch. Les deux options les plus courantes sont la méthode de la requête et le corps de la requête.

Pour illustrer leur utilisation, nous allons effectuer une requête POST vers l'API JSONPlaceholder. Voici le code pour cela :

async function getData() {
        const response = await fetch(
            "https://jsonplaceholder.typicode.com/posts", {
                 method: 'POST',
                 body: JSON.stringify({ 
                     title: 'Fetch API',
                     body: 'Lorem Ipsum',
                     userId: 1,
                 })
            }
        );

        if (response.status == 200) {
            const posts = await response.json();
            console.log(posts);
        } else {
            console.log("Une erreur s'est produite :", response.status);
        }
    }
    getData();

Dans notre objet options, nous avons spécifié la méthode de requête et le corps comme propriétés. Pour ces deux propriétés, nous avons fourni des chaînes de caractères en argument. Nous avons fourni la chaîne 'POST' pour la méthode de requête, car nous souhaitons effectuer une requête POST. Nous avons aussi fourni une chaîne JSON pour la propriété body. Cette chaîne JSON est obtenue en transformant un objet avec les propriétés nécessaires en chaîne.

L'exécution de ce code dans le navigateur produit le résultat suivant :

Le résultat est un objet qui contient l'ID que nous venons de recevoir du serveur. Vous trouverez une ressource exhaustive répertoriant toutes les options que vous pouvez passer.

Erreurs fréquentes lors de l'utilisation de l'API Fetch de JavaScript

#1. Erreurs réseau

Il est fréquent de rencontrer des erreurs lors des requêtes réseau. La fonction fetch renvoie une promesse qui se résout avec le résultat ou est rejetée si une erreur réseau survient. Il est donc impératif d'encapsuler le code dans un bloc try/catch pour gérer les erreurs réseau de manière appropriée.

#2. Autres erreurs

En dehors des erreurs réseau, vous pouvez rencontrer d'autres erreurs, comme les codes 404, 403, ou 500. La fonction fetch ne génère pas d'erreur lors de telles situations. Il faut donc les vérifier manuellement en examinant le code de statut de la réponse. Dans les exemples précédents, nous n'avons analysé le corps de la réponse que si le code de statut était 200.

#3. Erreurs CORS

Les erreurs CORS sont aussi des erreurs courantes. CORS signifie "Partage des Ressources Inter-Origines". Une origine est définie par la combinaison unique du protocole, de l'hôte et du port d'un serveur. Par exemple, mon site web peut s'exécuter sur localhost, qui est l'hôte, sur le port 5500, et servi via HTTP, le protocole. L'origine de ce site serait donc http://localhost:5500.

Ce même site web peut effectuer une requête API vers l'API https://jsonplaceholder.typicode.com, qui a une origine différente. Ainsi, ces deux origines, localhost et JSONPlaceholder, partagent des ressources. C'est cela le partage de ressources inter-origines. Toutefois, le serveur API doit activer CORS pour que cela fonctionne, ce qui n'est pas toujours le cas. La solution dans ce cas est de réaliser les requêtes via un serveur proxy qui supporte CORS.

Compatibilité navigateur

L'API Fetch est une fonctionnalité assez récente. Selon CanIUse.com, environ 95% des utilisateurs dans le monde utilisent des navigateurs qui la prennent en charge.

Conclusion

L'API Fetch de JavaScript représente une méthode plus élégante et claire pour concevoir des interfaces qui effectuent des requêtes API. Cependant, en raison de sa compatibilité navigateur limitée, vous pourriez envisager d'autres bibliothèques clients HTTP.