La plupart des applications Web modernes communiquent en permanence avec un serveur. L’API JavaScript Fetch est le moyen standard de le faire, et elle est intégrée aux navigateurs et à Node.js 18 et versions ultérieures, il n’y a donc rien à installer.

L’utilisation de base prend deux lignes, mais de nombreux tutoriels s’arrêtent là et laissent de côté la partie qui provoque de vrais bugs : la gestion des échecs. Nous avons testé les exemples de ce guide sur un petit serveur local sur Node.js 24, et le résultat affiché provient de cette exécution. example.com dans le code représente votre propre API. Si les promesses sont nouvelles pour vous, commencez par Explication des promesses JavaScript.

Qu’est-ce que l’API Fetch ?

Fetch est une interface basée sur des promesses pour effectuer des requêtes HTTP. Il a remplacé l’ancien, basé sur le rappel XMLHttpRequest, et de nombreux projets l’utilisent désormais plutôt que d’ajouter une bibliothèque pour des appels simples.

Une requête GET

Fetch effectue une requête GET par défaut. Il y a deux étapes, et chacune nécessite await : d’abord les en-têtes de réponse arrivent, puis vous lisez le corps.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

Les deux étapes existent car le corps peut être volumineux et arriver plus tard que les en-têtes. Dans un script de navigateur, le niveau supérieur await a besoin d’un module, vous le placerez donc généralement dans une fonction async. Consultez notre Guide asynchrone/attente JavaScript.

L’objet Réponse

Avant de lire le corps, vous pouvez inspecter la réponse :

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Un corps ne peut être lu qu’une seule fois. L’appel de json() une deuxième fois a échoué lors de notre test :

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Si vous devez le lire deux fois, appelez d’abord response.clone().

La grosse surprise : une 404 ne lance pas

C’est la chose la plus importante dans cet article. Nous avons demandé à un utilisateur qui n’existe pas :

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

Aucune exception n’a été levée. En ce qui concerne le fetch, la requête a fonctionné : le serveur a été atteint et il a répondu. La promesse n’est rejetée que lorsqu’aucune réponse utilisable n’arrive, comme en cas de panne de réseau. Un code comme celui-ci a donc un bug caché :

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Consultez notre aide-mémoire sur les codes d’état HTTP pour voir la signification de chaque code.

Une aide réutilisable

Ne répétez pas cette vérification partout. Enveloppez-le une fois :

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Désormais, les erreurs HTTP et les erreurs réseau se retrouvent toutes deux dans le même catch. Cette petite fonction vaut la peine d’être présente dans chaque projet. Une version réelle peut également lire un message d’erreur dans le corps de la réponse et gérer une réponse 204 No Content, qui n’a pas de JSON à analyser.

Données POST-JSON

Passez un objet options comme deuxième argument. Pour JSON, vous devez faire deux choses vous-même : convertir les données en chaîne et définir l’en-tête.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Notre serveur de test a renvoyé le type de contenu qu’il a reçu, confirmant l’arrivée de l’en-tête. Oublier cet en-tête est une cause fréquente d’erreurs de serveur confuses, car de nombreux frameworks n’analysent JSON que lorsqu’il est déclaré. Pour télécharger un formulaire ou des fichiers, transmettez un objet FormData comme corps et ne pas définissez Content-Type, car le navigateur doit lui-même ajouter une valeur limite.

Autres méthodes et options

Choisir entre REST et d’autres styles d’API ? Notre comparaison de REST vs GraphQL montre comment la récupération s’adapte à chacun.

Chaînes de requête

Ne créez pas de chaînes de requête en joignant du texte, car les caractères spéciaux les briseraient. URLSearchParams gère l’encodage pour vous :

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

Le serveur a reçu red shoes correctement, avec l’espace restauré.

Délais d’attente et annulation

Fetch attendra longtemps sur un serveur lent, sauf indication contraire de votre part. AbortSignal.timeout() fixe une limite. Notre point final de test a duré deux secondes, contre une limite de 200 millisecondes :

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Pour annuler manuellement, par exemple lorsqu’un utilisateur quitte une page ou saisit un nouveau terme de recherche, utilisez un AbortController :

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Pour exécuter plusieurs requêtes à la fois, utilisez Promise.all, ce qui est beaucoup plus rapide que de les attendre une à la fois :

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Toutes sortes d’échecs

Voici à quoi ressemblait chaque échec lors de notre analyse, ainsi que comment les distinguer :

Cette dernière rangée est courante en production. Un proxy renvoyant un 502 envoie souvent une page d’erreur HTML. Nous avons reproduit cela et res.json() a lancé un SyntaxError. Cocher response.ok avant l’analyse signifie que vous signalez le vrai problème plutôt qu’une erreur d’analyse déroutante.

CORS et informations d’identification

Dans un navigateur, une requête d’une origine à une autre est soumise à CORS, les règles de partage de ressources entre origines. Si vous voyez une erreur mentionnant Access-Control-Allow-Origin, le correctif appartient au serveur, qui doit autoriser votre site. Dans votre JavaScript, l’échec n’apparaît que sous forme générique TypeError, alors regardez la console du navigateur pour connaître la raison réelle. Node.js n’applique pas CORS, donc une requête qui fonctionne dans un script peut toujours échouer dans le navigateur.

Par défaut, les navigateurs n’envoient pas de cookies sur les requêtes cross-origin. Définissez credentials: "include" si vous en avez besoin et assurez-vous que le serveur le permet. Ne mettez jamais de clés API secrètes dans le JavaScript du navigateur, car tout le monde peut les lire. Gardez-les sur votre serveur.

Erreurs courantes

• Ne pas vérifier response.ok. Les réponses d’erreur sont traitées comme un succès.
• Oublier le deuxième await. response.json() renvoie également une promesse.
• Oublier JSON.stringify. Passer un objet au fur et à mesure que le corps l’envoie [object Object].
• Régler Content-Type avec FormData. Cela brise la limite, alors laissez-la de côté.
• N’avoir aucun délai d’attente. Une requête bloquée peut laisser le spinner d’une page fonctionner indéfiniment.
• Analyse JSON pour une réponse vide. Un 204 n’a pas de corps et json() le lancera.

Pour conclure

La récupération est simple une fois que l’on se souvient de sa règle principale : une réponse n’est pas la même chose qu’un succès. Copiez le petit assistant dans votre projet, ajoutez un délai d’attente et testez vos chemins d’échec. Dans l’étape suivante, créez une petite page qui charge les données d’une API, affiche un message d’erreur clair et permet à l’utilisateur d’annuler une recherche lente.

Questions fréquentes

Continuez à apprendre