Fetch et API du navigateur : récupérer des données

Une API web permet à un programme de lire ou de modifier des données au moyen d’URL nommées, appelées points de terminaison. Le JavaScript de la page est le client. Il envoie une requête HTTP ; le serveur répond avec une réponse HTTP. De nombreuses API envoient du texte JSON, qui peut représenter des objets, des tableaux, des chaînes de caractères, des nombres, des booléens et null.

Lire une requête

Prenons GET https://api.example.com/books?author=Le%20Guin&limit=5. La méthode est GET, le chemin /books sélectionne la ressource et la chaîne de requête contient deux paramètres. La valeur de author est « Le Guin » ; %20 encode l’espace. Une esperluette sépare les paramètres. La documentation de l’API explique les noms de paramètres acceptés et le sens de chaque valeur.

Une requête peut aussi transporter des en-têtes, qui sont des paires nom-valeur, et un corps, qui contient les données soumises. Accept: application/json demande une réponse JSON. Content-Type: application/json décrit le corps envoyé. Authorization transporte des identifiants. Les noms d’en-tête ne tiennent pas compte de la casse : content-type et Content-Type désignent donc le même en-tête.

Choisir l’action

GET et HEAD sont des méthodes sûres : elles sont destinées à la lecture. N’utilise donc pas GET pour un bouton de suppression. GET, PUT et DELETE sont idempotentes. Répéter la même requête laisse le serveur dans le même état attendu qu’une seule exécution. Supprimer une note déjà supprimée peut renvoyer un code d’état différent, mais la note reste absente. Répéter un POST peut créer un second enregistrement.

Interpréter la réponse

La réponse contient un code d’état, des en-têtes et généralement un corps. Le premier chiffre classe le résultat :

• 2xx : succès. 200 OK contient généralement des données, 201 Created indique une création et 204 No Content n’a pas de corps.
• 3xx : redirection. Par défaut, fetch suit les redirections.
• 4xx : problème lié à la requête ou à l’accès. 400 signifie que la requête est incorrecte ; 401, que les identifiants sont absents ou invalides ; 403, que le serveur comprend la requête mais la refuse ; 404, que la ressource est introuvable ; 429, qu’il y a trop de requêtes.
• 5xx : problème de serveur, comme 500 Internal Server Error ou 503 Service Unavailable.

Un appel à /books/42 peut renvoyer 200, un type de contenu JSON et {"id":42,"title":"The Dispossessed","year":1974}. Un appel à /books/9999 peut renvoyer 404 et {"error":"Book not found"}. Les deux appels ont reçu une réponse. Une erreur de connexion ne produit aucun code d’état HTTP que JavaScript puisse examiner.

Examiner avant de supposer

Ouvre les outils de développement, sélectionne Réseau et déclenche l’action. Examine la méthode, l’URL complète, le code d’état, les en-têtes, le corps et les durées. Compare-les au point de terminaison, aux paramètres obligatoires, aux identifiants, aux limites de requêtes et à l’exemple de réponse de la documentation. Si le serveur a renvoyé les bonnes données, examine le code de la page ; si l’URL de la requête est incorrecte, corrige-la avant de modifier le code de rendu.

fetch(url) envoie une requête GET et renvoie une promesse. Son résultat est un objet Response, disponible à l’arrivée des en-têtes. La lecture du corps est une opération asynchrone distincte. response.json() lit ce corps et l’analyse pour obtenir des données JavaScript.

Attendre, vérifier, lire

async function loadBook(id) {
  const response = await fetch(`https://api.example.com/books/${id}`);
  if (!response.ok) {
    throw new Error(`HTTP error ${response.status}`);
  }
  return await response.json();
}

Pour loadBook(42), le premier await obtient la réponse. La condition rejette un résultat HTTP indiquant un échec. Le second await obtient le livre analysé, par exemple { id: 42, title: "The Dispossessed", year: 1974 }. La fonction elle-même renvoie une promesse : son appelant attend donc aussi le résultat.

response.ok est vrai pour les codes d’état de 200 à 299 inclus. Une erreur HTTP comme 404 ou 500 ne provoque pas le rejet de la promesse de fetch : un serveur a répondu. Une panne réseau, un échange bloqué par CORS, une URL de requête invalide ou une annulation peuvent provoquer son rejet. Lever une exception pour !response.ok permet à un bloc try/catch englobant de gérer aussi les échecs HTTP.

Comprendre le corps

Sans await, const data = response.json() stocke une promesse, pas le livre. L’accès à data.title donne alors undefined. Omettre await devant fetch laisse de même une promesse là où le code attend un objet Response.

Choisis la méthode de lecture adaptée au corps de la réponse : json() pour le JSON, text() pour le texte ou blob() pour les données binaires. Un corps ne peut être consommé qu’une fois. Stocke le résultat analysé et réutilise-le. Pour examiner aussi le texte JSON brut, lis text() une fois, puis appelle JSON.parse(text) sur la chaîne stockée.

Du JSON invalide entraîne un rejet avec une SyntaxError. Une page d’erreur HTML provoque souvent un message « Unexpected token '<' ». Un corps vide, notamment dans une réponse 204, ne peut pas non plus être analysé comme du JSON. Vérifie d’abord le code d’état et examine response.headers.get("Content-Type") en cas de doute sur le format. Un code d’état de succès ne garantit pas à lui seul que le corps contient du JSON.

Construire une requête en toute sécurité

const url = new URL("https://api.example.com/search");
url.searchParams.set("q", "rock & roll");
url.searchParams.set("limit", 10);

L’adresse obtenue est https://api.example.com/search?q=rock+%26+roll&limit=10. L’esperluette incluse dans la valeur est encodée comme partie de celle-ci. Ajouter directement la saisie à "?q=" peut donner à &, # ou + leur signification dans une URL et modifier la recherche. Une URL relative suit les règles habituelles de résolution des adresses : depuis https://notes.example.org/app/index.html, fetch("data/books.json") charge /app/data/books.json sur cette origine.

Suivre la structure renvoyée

Pour {"results":[{"title":"Dune"}],"total":1}, le premier titre est data.results[0].title. L’objet englobant n’est pas le tableau de résultats. Utilise l’aperçu de la réponse pour trouver le tableau avant de le parcourir.

Une fonction utilitaire partagée getJSON(url, options) peut effectuer la même vérification du code d’état et la même lecture du corps pour de nombreux appels. Dans une chaîne .then(), renvoie response.json() depuis la fonction de rappel de la réponse afin que la suivante reçoive les données analysées. Ajoute .catch() à la fin pour gérer les étapes rejetées.

Le second argument de fetch configure une requête. Ses options comprennent method, headers, body, signal et credentials. Sans ces options, la requête est un GET sans corps. Pour soumettre du JSON, tu dois préparer son texte et son type de contenu.

Envoyer du JSON

const response = await fetch("https://api.example.com/notes", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Shopping", text: "Rice, lentils" }),
});

JSON.stringify produit {"title":"Shopping","text":"Rice, lentils"}. L’en-tête indique au serveur comment lire ce texte. Passer directement l’objet comme corps envoie "[object Object]". Envoyer la chaîne JSON sans l’en-tête lui attribue le type text/plain;charset=UTF-8, que de nombreux points de terminaison JSON rejettent avec 400 ou 415 Unsupported Media Type.

Une création réussie renvoie souvent 201 avec l’enregistrement stocké, par exemple {"id":17,"title":"Shopping","text":"Rice, lentils"}. Utilise l’objet renvoyé pour mettre la page à jour : le nouvel id attribué par le serveur est nécessaire pour les modifications et la suppression ultérieures.

Remplacer ou mettre à jour

Un corps PUT qui omet un champ peut entraîner sa suppression ou sa réinitialisation, selon l’API. Utilise la méthode documentée pour la modification souhaitée. PUT et PATCH peuvent renvoyer un enregistrement mis à jour avec 200, ou renvoyer 204 sans corps.

Gère le succès sans supposer qu’il est toujours suivi de JSON :

if (!response.ok) {
  throw new Error(`HTTP error ${response.status}`);
}
const saved = response.status === 204
  ? null
  : await response.json();

Ce schéma convient aux points de terminaison documentés comme renvoyant soit du JSON, soit 204. Une suppression peut réussir et produire tout de même une erreur d’analyse syntaxique si le code appelle systématiquement json() sur son corps vide.

Choisir le format du corps

new FormData(formElement) recueille les champs nommés du formulaire et les fichiers sélectionnés. Passe-le directement comme body. Laisse le navigateur définir Content-Type: multipart/form-data et son délimiteur ; un en-tête fourni manuellement peut omettre le délimiteur nécessaire pour séparer les champs. Un corps URLSearchParams utilise application/x-www-form-urlencoded.

GET et HEAD ne peuvent pas transporter de corps avec fetch. Place les termes de recherche et les filtres dans la chaîne de requête de l’URL. Une tentative de GET avec un corps est rejetée avec une TypeError avant de pouvoir servir de requête de recherche.

Terminer correctement après un succès ou un échec

Désactive le bouton de soumission avant d’attendre une requête de création, puis réactive-le dans finally. Sinon, un double clic peut envoyer deux requêtes POST et créer deux enregistrements. Ne répète pas automatiquement une opération de création dont le résultat est incertain : une réponse perdue ne permet pas de savoir si le serveur a effectué la modification.

Pour un code d’état d’erreur, le corps peut contenir un message utile comme {"error":"title is required"}. Lis-le une fois s’il s’agit de JSON ; intercepte une erreur d’analyse et conserve un message HTTP général pour les réponses vides ou HTML. Garde le texte saisi par l’utilisateur afin qu’il puisse corriger la requête.

Le rendu transforme un tableau ou un objet en éléments sur la page. Conserve les données récupérées dans une variable et donne-les à une fonction de rendu. Cette séparation permet de trier ou de filtrer les mêmes données sans les redemander au serveur.

Créer un élément par résultat

function renderBooks(books, list) {
  list.replaceChildren();
  for (const book of books) {
    const item = document.createElement("li");
    item.textContent = `${book.title} (${book.year})`;
    list.append(item);
  }
}

Pour [{"title":"Kindred","year":1979},{"title":"Beloved","year":1987}], ce code crée deux éléments de liste : « Kindred (1979) » et « Beloved (1987) ». Vider d’abord le conteneur permet à une nouvelle recherche de remplacer la précédente. Sans cette étape, les anciennes et les nouvelles listes s’accumulent.

Conserver le texte externe sous forme de texte

Utilise textContent pour les titres, descriptions et autres textes d’une API. innerHTML analyse une chaîne comme du balisage. Un titre contenant <img src="x" onerror="alert(1)"> peut alors exécuter du code. C’est une injection de script intersite, ou XSS. Le texte provenant des formulaires et du stockage nécessite le même traitement, car il peut lui aussi provenir d’une source non fiable.

Les propriétés des éléments définissent des valeurs individuelles, comme img.alt = book.title. Elles ne rendent pas automatiquement sûrs tous les types de valeurs. Un lien fourni par une API nécessite toujours une vérification du protocole :

try {
  const target = new URL(book.url, location.href);
  if (target.protocol === "https:" || target.protocol === "http:") {
    link.href = target.href;
  }
} catch {
  link.removeAttribute("href");
}

Ce code s’exécute sur un lien nouvellement créé, sans href existant. Une URL invalide ou non autorisée le laisse sans destination. Une URL javascript: n’est pas une navigation web ordinaire. Pour les images, fournis si possible un texte alt pertinent construit à partir des données.

Fournir des valeurs par défaut sans perdre les valeurs réelles

Les champs facultatifs peuvent être absents ou valoir null. book.author?.name ?? "Unknown author" essaie d’abord d’obtenir le nom imbriqué, puis fournit une valeur par défaut. Le chaînage optionnel évite d’accéder à une propriété d’un auteur absent.

L’opérateur compte : 0 || "n/a" donne "n/a", tandis que 0 ?? "n/a" conserve 0. L’opérateur || remplace toutes les valeurs fausses dans un contexte booléen, notamment zéro et une chaîne vide ; ?? ne remplace que null et undefined. Pour un livre dont aucun exemplaire n’est disponible, il faut afficher zéro.

Un tableau de résultats vide correspond à une recherche réussie sans résultat. Affiche « Aucun livre ne correspond à ta recherche. » pour que les lecteurs puissent le distinguer d’une page qui n’a pas été chargée.

Remplacer une recherche, ajouter une autre page

De nombreuses API renvoient des pages à l’aide de page, limit, d’un nombre total ou d’une URL next. Avec 47 résultats et 10 par page, quatre pages complètes contiennent 40 enregistrements et la cinquième en contient 7. Une nouvelle recherche efface la liste précédente ; « Charger plus » ajoute la page suivante à la liste actuelle. Distingue bien ces deux actions d’affichage.

Pour trier une copie locale de la plus récente à la plus ancienne, utilise [...books].sort((a, b) => b.year - a.year) et affiche cette copie. La décomposition crée un nouveau tableau : l’ordre de la réponse enregistrée reste donc disponible. Examine la structure de la réponse avant de sélectionner le tableau : une API paginée le place souvent dans data.results.

Les API renvoient des valeurs faciles à échanger pour les programmes. Les lecteurs ont besoin de dates, d’heures et de montants mis en forme selon leur langue et leur région. Sépare la valeur stockée du texte utilisé pour l’afficher.

Lire d’abord le format de date

"2026-03-05T14:30:00Z" désigne un instant : le 5 mars 2026 à 14 h 30 UTC. Le Z signifie UTC. new Date(...) le convertit en objet JavaScript Date. Une chaîne contenant uniquement une date, comme "2026-03-05", est interprétée comme minuit UTC ; une date et une heure sans décalage, comme "2026-03-05T14:30", sont interprétées comme une heure locale.

Un horodatage Unix compte le temps écoulé depuis le 1er janvier 1970, UTC. Les API comptent souvent en secondes, mais Date utilise les millisecondes. new Date(1772721000 * 1000) donne le même instant du 5 mars. Omettre la multiplication donne une date en janvier 1970. Lis la documentation de l’API pour identifier l’unité.

Choisir des paramètres régionaux et un fuseau horaire

const date = new Date("2026-03-05T14:30:00Z");
const dateFormat = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "UTC",
});
dateFormat.format(date);

La sortie est « Mar 5, 2026, 2:30 PM ». Avec en-GB, elle est « 5 Mar 2026, 14:30 ». Les dates courtes donnent « 3/5/26 » en en-US, « 05/03/2026 » en en-GB et « 05.03.26 » en de-DE.

Les paramètres régionaux contrôlent la présentation ; le fuseau horaire détermine l’heure locale. Sans timeZone, l’outil de mise en forme utilise le fuseau de l’appareil. Cet instant correspond à 9 h 30 à New York, 15 h 30 à Amsterdam et 23 h 30 à Tokyo. Conserve et envoie les instants en UTC, puis convertis-les pour l’affichage. Une date du calendrier comme un anniversaire demande de l’attention : afficher minuit UTC dans un fuseau situé à l’ouest d’UTC peut donner le jour précédent.

Séparer la devise des paramètres régionaux

const priceFormat = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "EUR",
});
priceFormat.format(1234.5);

Cela donne €1,234.50. Pour le même montant, de-DE avec EUR donne 1.234,50 € ; en-US avec USD donne $1,234.50 ; en-US avec JPY donne ¥1,235. JPY n’a pas d’unité monétaire divisionnaire : son affichage habituel ne comporte donc aucune décimale. Le choix des paramètres régionaux ne convertit pas les devises. Utilise le code de devise fourni avec le montant.

Certaines API de paiement envoient des unités divisionnaires sous forme d’entiers. Avec USD, 1999 cents représentent 19.99 dollars américains : divise par 100 avant la mise en forme. N’applique pas ce diviseur à JPY. Additionner des cents entiers donne 1999 + 2550 = 4549, ce qui est mis en forme comme $45.49. Cela évite le résultat bien connu du calcul décimal 0.1 + 0.2, qui vaut 0.30000000000000004.

Réutiliser l’outil de mise en forme

Crée une seule fois un outil de mise en forme pour une liste. Utilise undefined comme paramètres régionaux pour sélectionner ceux du navigateur par défaut ; navigator.language indique le code de langue préféré du navigateur. D’autres options mettent en forme 0.256 comme « 26% », ou 12.5 avec l’unité "kilometer-per-hour" comme « 12.5 km/h ». new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(-1, "day") donne « yesterday ». Les dates construites à la main comme « 03/05/2026 » restent ambiguës selon les régions.

Une requête a un cycle de vie visible : inactive, en chargement, puis réussie ou en erreur. Le succès peut contenir des données ou un résultat vide. La page doit expliquer chaque état pour que les lecteurs sachent s’ils doivent attendre, modifier une recherche ou réessayer.

Regrouper la préparation et la remise en état

Dans ce gestionnaire, getJSON vérifie le code d’état HTTP et analyse le corps, searchUrl construit l’URL de la requête et renderResults met la liste à jour. Le bouton et l’élément d’état existent déjà dans la page.

async function search(query) {
  button.disabled = true;
  status.textContent = "Loading…";
  try {
    const data = await getJSON(searchUrl(query));
    renderResults(data.results);
    status.textContent = data.results.length === 0 ? "No results." : "";
  } catch (error) {
    status.textContent = "Could not load results. Check your connection and try again.";
    console.error(error);
  } finally {
    button.disabled = false;
  }
}

La préparation a lieu avant l’attente. En cas de succès, le code affiche les résultats et gère un tableau vide. Le bloc catch remplace le message de chargement si une étape attendue échoue. finally rétablit le bouton dans les deux cas. Si la remise en état n’avait lieu qu’après un await réussi, un échec laisserait la commande désactivée.

Expliquer la cause utile

Une erreur HTTP possède un code d’état qui aide à formuler le message. Pour 404, indique que l’élément est introuvable. Pour 401, demande à l’utilisateur de se connecter ; pour 403, explique que l’accès n’est pas autorisé. Pour 429, demande-lui de patienter. Pour 5xx, explique que le service rencontre un problème et propose de réessayer plus tard.

Une TypeError provenant de fetch peut indiquer une panne réseau, une requête bloquée par CORS ou une URL incorrecte. JavaScript ne reçoit pas de diagnostic CORS détaillé et fiable ; examine la console du navigateur et l’onglet Réseau. Une SyntaxError provenant de json() indique du JSON invalide. L’annulation et les limites de durée produisent des erreurs comme AbortError et TimeoutError. Garde les détails techniques dans la console et indique aux lecteurs une action qu’ils peuvent comprendre.

Rendre les changements perceptibles

Utilise un élément d’état existant comme <p role="status"></p>. Ses changements sont annoncés aux lecteurs d’écran sans déplacer le focus. aria-live="polite" remplit un rôle similaire ; role="alert" convient aux erreurs urgentes. Un indicateur de chargement seul ne signale pas un résultat vide ou une requête échouée.

Un bouton Réessayer appelle à nouveau la fonction de chargement. Répéter sans modification des requêtes ayant reçu 400 ou 404 reproduit généralement le problème. Des pannes temporaires du réseau ou du service peuvent justifier une courte série limitée de nouvelles tentatives. L’attente exponentielle augmente la pause, par exemple 1 seconde, 2 secondes, puis 4 secondes. Respecte l’en-tête de réponse Retry-After ; il peut indiquer un délai en secondes ou une date HTTP. Évite de répéter automatiquement une requête de création qui a peut-être déjà réussi.

Si une actualisation échoue mais que les données précédentes sont encore utiles, laisse-les visibles avec une note comme « Résultats de 10 h 42 affichés. Actualisation impossible. » Ne laisse pas croire silencieusement que les anciens résultats sont à jour.

Tester les cas difficiles

Utilise les outils de développement pour ralentir la connexion, passer hors ligne et demander un chemin inexistant. Vérifie que le chargement apparaît rapidement, qu’une requête échouée le remplace, qu’un succès sans résultat a son propre message et que les commandes redeviennent utilisables.

Les requêtes peuvent durer plus longtemps que l’action qui les a lancées. Une réponse de recherche peut arriver après que le lecteur a saisi autre chose, et un service lent peut laisser une page attendre trop longtemps. Contrôle si les résultats sont encore pertinents, ainsi que la réussite de chaque requête.

Annuler le travail devenu inutile

Crée un AbortController, passe son signal à fetch, puis appelle abort() pour annuler la requête. L’annulation peut interrompre l’attente des en-têtes ou une lecture du corps en cours. L’erreur de rejet est normalement nommée "AbortError".

const controller = new AbortController();
const response = await fetch(url, { signal: controller.signal });
// A cancel button can call controller.abort().
const data = await response.json();

Gère les erreurs autour des deux attentes. Si ton code annule volontairement une recherche obsolète, termine silencieusement pour cette annulation attendue au lieu d’indiquer à l’utilisateur que le service a échoué.

fetch ne possède pas d’option timeout intégrée. Utilise un signal comme AbortSignal.timeout(5000) pour limiter la requête à 5 000 ms, soit 5 secondes de temps actif. Avant l’arrivée des en-têtes, la promesse est rejetée avec TimeoutError ; après leur arrivée, le délai peut interrompre la lecture du corps.

Empêcher les anciennes recherches de prendre le dessus

Une condition de concurrence se produit lorsque l’ordre d’achèvement modifie le résultat. Un lecteur saisit « ch », puis « chat ». Si la réponse pour « ch » arrive en dernier et est affichée, l’écran ne correspond plus à la saisie.

Une approche annule la requête précédente avant chaque nouvelle requête. Une autre attribue un numéro à chaque appel et ne laisse que le plus récent mettre la page à jour :

let latest = 0;
async function search(query) {
  const request = ++latest;
  try {
    const data = await getJSON(searchUrl(query));
    if (request !== latest) return;
    renderResults(data.results);
  } catch (error) {
    if (request !== latest) return;
    showError(error);
  }
}

Cette vérification empêche aussi un ancien échec de remplacer un succès plus récent. Applique la même vérification de pertinence aux messages de chargement et à la remise en état des commandes lorsque les appels se chevauchent.

L’anti-rebond réduit le nombre d’appels lancés. Efface la minuterie précédente à chaque frappe et démarre-en une nouvelle, par exemple de 300 ms. Saisir rapidement « paris » lance alors une seule requête après la pause. L’anti-rebond économise des requêtes ; il n’empêche pas à lui seul une réponse à un appel précédent encore en cours d’arriver tardivement.

Décider ce qui peut s’exécuter ensemble

Des requêtes indépendantes peuvent être lancées ensemble :

const [user, posts] = await Promise.all([
  getJSON(userUrl),
  getJSON(postsUrl),
]);

Pour des durées de 300 ms et 500 ms, les deux prennent environ 500 ms au lieu d’environ 800 ms en séquence. Promise.all est rejetée dès que l’une des promesses fournies est rejetée, mais elle n’annule pas les autres opérations.

Utilise Promise.allSettled lorsque des résultats partiels sont utiles. Elle attend toutes les promesses fournies et indique chaque résultat sous la forme { status: "fulfilled", value } ou { status: "rejected", reason }. Un tableau de bord peut ainsi afficher les panneaux ayant réussi à côté de celui qui a échoué.

Les requêtes dépendantes doivent rester en séquence. Si une seconde URL nécessite un identifiant renvoyé par la première requête, attends cet identifiant avant de construire la seconde requête.

Une origine combine le schéma, l’hôte et le port d’une URL. Le chemin n’en fait pas partie. https://shop.example.com/cart et /help sur le même site partagent une origine. Passer à http://shop.example.com, https://api.example.com ou https://shop.example.com:8443 change l’origine. HTTPS utilise normalement le port 443.

Qui autorise la lecture de la réponse ?

La politique de même origine limite les ressources qu’un script de page peut lire. Pour une récupération depuis une autre origine, CORS permet au serveur de l’API d’accorder l’accès au moyen d’en-têtes de réponse. Une page sur https://notes.example.org qui appelle https://api.example.com/weather a besoin de l’autorisation de l’API pour lire la réponse.

Access-Control-Allow-Origin: https://notes.example.org accorde l’accès à cette origine. La valeur * autorise toutes les origines pour une requête sans identifiants. Si la réponse ne contient pas d’autorisation correspondante, le navigateur la cache à la page et fetch est rejeté avec une TypeError. La console fournit le diagnostic CORS ; JavaScript ne reçoit pas la raison détaillée.

Ajouter Access-Control-Allow-Origin à la requête JavaScript n’accorde pas d’autorisation. C’est un en-tête de réponse contrôlé par le serveur. Ajouter un en-tête de requête personnalisé peut au contraire provoquer une vérification préliminaire supplémentaire.

Pourquoi OPTIONS apparaît avant POST

Certaines requêtes vers une autre origine nécessitent une requête préliminaire. Le navigateur envoie d’abord OPTIONS, en indiquant la méthode prévue dans Access-Control-Request-Method et les noms des en-têtes non autorisés par défaut dans Access-Control-Request-Headers. Le serveur les autorise avec Access-Control-Allow-Methods et Access-Control-Allow-Headers, en plus de l’autorisation de l’origine.

Un GET, HEAD ou POST simple, avec seulement des en-têtes autorisés, peut éviter la requête préliminaire. Les types de contenu autorisés comprennent text/plain, application/x-www-form-urlencoded et multipart/form-data. Un POST JSON, un en-tête Authorization, PUT ou DELETE nécessite une requête préliminaire, sauf si une autorisation antérieure valide est en cache. Si la requête préliminaire est refusée, la requête réelle n’est pas envoyée.

Pour une requête simple, la requête réelle peut atteindre le serveur même si le navigateur bloque ensuite la lecture de sa réponse. CORS ne remplace donc pas l’autorisation côté serveur ni la vérification des entrées.

Les cookies ajoutent une exigence

La valeur par défaut credentials: "same-origin" n’envoie les cookies que pour les requêtes de même origine. credentials: "include" autorise également les cookies admissibles dans les requêtes vers d’autres origines. Les règles SameSite des cookies et les politiques relatives aux cookies tiers continuent de s’appliquer.

Pour permettre à JavaScript de lire une réponse associée à des identifiants, le serveur doit envoyer Access-Control-Allow-Credentials: true et nommer explicitement l’origine de la page. Access-Control-Allow-Origin: * ne fonctionne pas avec des identifiants. Ces en-têtes ne forcent pas un navigateur à envoyer un cookie qui serait autrement bloqué.

Diagnostiquer sans masquer le problème

mode: "no-cors" donne une réponse opaque avec l’état 0, sans corps ni en-têtes lisibles. Elle ne peut pas fournir de JSON à une page. Une requête qui fonctionne dans curl ne prouve pas non plus que CORS l’autorise dans le navigateur : les clients de terminal n’appliquent pas cette politique du navigateur.

Examine la console et l’onglet Réseau. Vérifie si la requête préliminaire a échoué ou si la réponse finale ne contenait pas l’autorisation nécessaire. Corrige la configuration des réponses de l’API ou fais passer l’appel par ton propre serveur. Pendant le développement, sers les pages depuis un serveur local : les pages file:// ont souvent des origines opaques. Un serveur local a toujours besoin d’une autorisation CORS lorsqu’il appelle une origine différente.

Une clé d’API identifie une application qui appelle une API, pour l’utilisation, les limites et la facturation. Un jeton d’accès accorde un accès pour un utilisateur ou une session. Toute personne possédant un identifiant utilisable peut être en mesure d’agir avec les droits associés : décide donc où le placer avant de l’ajouter à une requête.

Les en-têtes protègent l’emplacement, pas le secret vis-à-vis de l’utilisateur

Les fournisseurs peuvent exiger Authorization: Bearer <token>, X-API-Key: <key> ou un paramètre de requête comme api_key. Suis la documentation de l’API. Un en-tête évite de placer l’identifiant dans une URL complète qui peut se retrouver dans des journaux et des outils d’analyse. Un en-tête Authorization ou personnalisé dans un appel vers une autre origine déclenche normalement une requête préliminaire.

Un en-tête reste visible dans les outils de développement. Les visiteurs peuvent examiner le JavaScript qu’ils téléchargent et les requêtes qu’il envoie. Minifier le code ou cacher une valeur derrière une variable ne la rend pas secrète.

Suivre la clé dans une requête météo

Supposons que le code du navigateur appelle https://api.weather.example/v1/current?city=Lima&key=sk_live_4f9a2c. Toute personne qui ouvre l’onglet Réseau peut copier la clé et utiliser le quota du compte. Déplacer cette valeur dans une variable d’environnement utilisée lors de la compilation ne sert à rien si la compilation l’insère dans le JavaScript envoyé à la page.

Un secret conservé sur un serveur change le parcours :

1. La page appelle son propre site à /api/weather?city=Lima.
2. Le serveur de ce site ajoute le secret et contacte le fournisseur météo.
3. Le serveur renvoie les données météo à la page sans inclure le secret dans la réponse.

Le serveur doit toujours contrôler l’accès à son point de terminaison et son utilisation. Conserver le secret du fournisseur sur un serveur ne rend pas inoffensive une utilisation publique illimitée.

Certains fournisseurs délivrent des clés pour navigateur destinées à être publiques. Applique les restrictions de domaine du fournisseur, limite les API autorisées et définis des quotas d’utilisation. N’utilise une clé de cette façon que si sa conception documentée le permet ; une clé serveur secrète ne devient pas une clé pour navigateur par l’ajout d’une restriction de domaine.

Réagir à une exposition

Ne place pas les fichiers d’identifiants sous contrôle de version, par exemple en indiquant .env dans .gitignore. Cela empêche que le fichier soit inclus dans un commit ; cela n’empêche pas une compilation côté client de publier une valeur intégrée au code. Si une clé est exposée, révoque-la et crée une clé de remplacement. La retirer du commit le plus récent laisse intacts l’historique antérieur et les éventuelles copies.

Protéger l’échange et réduire le gaspillage

Utilise HTTPS pour les appels d’API afin que les données et les identifiants soient chiffrés pendant leur transit. Un appel fetch d’une page HTTPS vers une API HTTP est bloqué comme contenu mixte. Le chiffrement n’empêche pas la personne qui utilise le navigateur de voir sa propre requête.

Une limite de requêtes plafonne l’utilisation, par exemple à 60 requêtes par minute. Les appels dépassant la limite peuvent renvoyer 429 Too Many Requests. Mets en cache les résultats appropriés, applique l’anti-rebond aux saisies de recherche et évite les appels en double. Si le serveur fournit Retry-After, respecte le délai indiqué au lieu de réessayer immédiatement à répétition.

La validation côté client facilite l’utilisation des formulaires, mais tout le monde peut appeler un point de terminaison sans passer par ton formulaire. Le serveur doit lui-même valider les requêtes et autoriser les actions. Lorsque tu affiches sa réponse, continue de traiter les chaînes comme du texte non fiable et insère-les avec textContent.

Web Storage propose deux espaces de stockage clé-valeur : localStorage et sessionStorage. Ils utilisent les mêmes méthodes : le choix principal porte donc sur la durée de conservation des données et les onglets qui doivent les partager.

Choisir la durée de vie

Fermer l’onglet met fin à son stockage de session. Une page nouvellement ouverte avec un élément déclencheur peut commencer avec une copie du stockage de session de cet élément, mais les modifications ultérieures restent distinctes. N’utilise pas le stockage de session pour garder des informations secrètes vis-à-vis des scripts.

Le stockage dépend des origines. https://app.example.com ne peut pas partager son stockage avec http://app.example.com. Les chemins d’une même origine le partagent : un préfixe comme "notes-app:settings" aide donc à distinguer les clés de plusieurs applications.

Utiliser les méthodes de stockage

localStorage.setItem("notes-app:theme", "dark");
const theme = localStorage.getItem("notes-app:theme");
localStorage.removeItem("notes-app:theme");

setItem crée ou écrase une entrée. getItem renvoie sa valeur sous forme de chaîne ou null si elle est absente. removeItem supprime une entrée. clear() supprime toutes les entrées de cet espace de stockage pour l’origine, ce qui peut affecter d’autres fonctionnalités du même site. length et key(index) permettent d’examiner les clés.

Utilise ces méthodes plutôt que des affectations de propriétés comme localStorage.theme = "dark". Des clés comme "length" ou "key" peuvent entrer en conflit avec des membres intégrés lorsqu’on y accède comme à des propriétés.

Convertir les valeurs explicitement

Après localStorage.setItem("count", 5), la lecture donne "5". Ajouter directement 1 produit "51". Number(localStorage.getItem("count")) + 1 produit 6.

Un booléen stocké présente un piège similaire. setItem("darkMode", false) stocke "false", et une chaîne non vide est une valeur vraie dans un contexte booléen. Lis avec localStorage.getItem("darkMode") === "true" lorsque ce sont les deux chaînes stockées attendues.

Les objets et les tableaux nécessitent JSON :

localStorage.setItem("settings", JSON.stringify({
  theme: "dark",
  fontSize: 18,
}));
const settings = JSON.parse(localStorage.getItem("settings"))
  ?? { theme: "light", fontSize: 16 };

Sans sérialisation, un objet ordinaire devient "[object Object]". JSON.parse(null) donne null, donc la valeur par défaut couvre le cas d’une entrée manquante. Une chaîne stockée mal formée nécessite toujours try/catch, et les données analysées doivent être vérifiées avant utilisation pour s’assurer qu’elles ont la bonne structure.

Limiter le travail

Les appels à Web Storage sont synchrones : JavaScript attend chacun d’eux sur le thread principal. Utilise-le pour des paramètres, un brouillon ou une courte liste, pas pour de grandes collections ou des fichiers. IndexedDB fournit un stockage asynchrone pour des données structurées plus volumineuses.

Les navigateurs actuels autorisent généralement environ 5 Mio dans chaque espace Web Storage par origine. Un stockage plein peut amener setItem à lever QuotaExceededError ; l’accès peut aussi échouer en raison des paramètres de confidentialité du navigateur. Gère l’échec sans empêcher le reste de l’application de fonctionner. Les outils de développement affichent les espaces de stockage dans l’onglet Application de Chrome et Edge ou dans l’onglet Stockage de Firefox, où la suppression d’entrées aide à tester les premières visites.

Une application charge généralement au démarrage et enregistre à chaque modification. Lis une liste enregistrée à l’ouverture de la page, affiche-la et enregistre la liste mise à jour après une modification. Le stockage du navigateur est une copie pratique : il peut être absent, endommagé, obsolète ou effacé.

Valider avant de restaurer

Cette fonction de chargement attend un tableau de chaînes enregistré :

function loadTodos() {
  try {
    const value = JSON.parse(localStorage.getItem("todos"));
    if (Array.isArray(value) && value.every(item => typeof item === "string")) {
      return value;
    }
  } catch {
    // Continue with an empty list if reading or parsing fails.
  }
  return [];
}

JSON.parse seul ne prouve pas que la valeur est un tableau ni que ses éléments conviennent à l’application. Une valeur JSON valide comme 42 n’a tout de même pas la bonne structure. Une valeur comportant une version comme { version: 2, todos: [...] } permet au code plus récent de reconnaître les anciens formats et de les convertir ou de restaurer une valeur par défaut.

Enregistre la liste en mémoire avec localStorage.setItem("todos", JSON.stringify(todos)) après chaque modification. Intercepte aussi les échecs d’écriture ; une page doit pouvoir continuer à fonctionner même si elle ne peut pas conserver l’état pour le prochain rechargement. Un brouillon de formulaire propre à une seule visite peut utiliser sessionStorage.

Horodater les réponses en cache

localStorage.setItem("weather", JSON.stringify({
  savedAt: Date.now(),
  data,
}));

Lors d’un chargement ultérieur, vérifie d’abord la structure et l’horodatage de l’objet en cache. Son âge est Date.now() - savedAt. Ne l’utilise que tant que cet âge est inférieur à 10 * 60 * 1000, soit 600 000 ms. Une valeur enregistrée à 10:00:00 a 450 000 ms à 10:07:30 et peut être utilisée. À 10:12:00, elle a 720 000 ms : récupère donc une nouvelle valeur. À exactement 600 000 ms, elle est expirée selon cette règle.

L’expiration relève de la logique de l’application : localStorage ne supprime pas une entrée lorsque ton intervalle de fraîcheur prend fin. Rejette un horodatage manquant ou invalide au lieu de considérer comme récente une donnée d’âge inconnu. Tu peux laisser des données périmées visibles lorsqu’une actualisation échoue si elles sont indiquées comme anciennes.

Synchroniser les autres onglets

Lorsqu’un onglet modifie localStorage, les autres onglets de la même origine reçoivent un événement storage. L’onglet qui écrit ne reçoit pas son propre événement. L’événement expose key, oldValue, newValue et url.

window.addEventListener("storage", (event) => {
  if (event.key === "theme") applyTheme(event.newValue);
});

Applique aussi immédiatement le thème dans l’onglet qui écrit. Gère null lorsqu’une clé est supprimée. Un événement de stockage ne remplace pas la mise à jour de l’état de ta propre page.

Décider de ce qui doit être conservé ailleurs

Ne place pas de mots de passe, de numéros de carte de paiement ou de clés d’API secrètes dans Web Storage. Les scripts de l’origine peuvent le lire, y compris le code tiers et les scripts injectés. Efface les données personnelles concernées à la déconnexion sur les appareils partagés. Conserve les travaux importants sur un serveur ou propose leur exportation, car les utilisateurs peuvent effacer les données du site et les sessions privées les suppriment.

Les cookies sont différents : les requêtes correspondantes les envoient au serveur, et les scripts de la page ne peuvent pas lire les cookies HttpOnly. Ils sont petits, environ 4 Ko chacun. Web Storage reste dans le navigateur et peut être lu par les scripts. IndexedDB convient aux données structurées plus volumineuses grâce à une API asynchrone.

La géolocalisation est une API du navigateur : une fonctionnalité fournie par le navigateur, distincte du langage JavaScript. Comme d’autres fonctionnalités de l’appareil, elle peut être indisponible ou refusée. Une page météo doit continuer à fonctionner lorsqu’un lecteur choisit de saisir une ville.

Vérifier la fonctionnalité et le contexte

Détecte la fonctionnalité elle-même avec "geolocation" in navigator. Vérifier le nom d’un navigateur est moins fiable : les versions et les paramètres modifient ce qui est disponible. La géolocalisation nécessite un contexte sécurisé, normalement HTTPS ; http://localhost convient aussi pour le développement. window.isSecureContext indique si la page actuelle remplit cette condition. Le simple HTTP sur l’adresse réseau d’un autre appareil n’est pas équivalent à localhost.

Explique pourquoi la position est utile et demande-la lorsque le lecteur clique sur « Utiliser ma position ». Le navigateur gère la demande d’autorisation. Une personne peut l’autoriser ou la bloquer, et un refus antérieur peut faire échouer un appel ultérieur sans nouvelle demande. L’utilisateur peut modifier cette décision dans les paramètres du site.

Lire le résultat de la fonction de rappel

navigator.geolocation.getCurrentPosition(success, error, options) utilise des fonctions de rappel. En cas de succès, position.coords contient la latitude et la longitude en degrés décimaux et accuracy en mètres. La précision correspond à un rayon d’incertitude estimé, pas à une précision décimale supplémentaire. En cas d’échec, le code 1 signifie que l’autorisation est refusée, 2 que la position est indisponible et 3 que le délai a expiré.

Les options contrôlent la tentative :

• enableHighAccuracy : demande une meilleure précision ; valeur par défaut false.
• timeout : limite d’attente en millisecondes ; valeur par défaut Infinity.
• maximumAge : âge maximal d’une position en cache acceptable ; valeur par défaut 0.

Utilise un délai fini pour que la page puisse sortir de l’attente. watchPosition observe les mises à jour au fil du temps et renvoie un identifiant ; passe cet identifiant à clearWatch lorsque le suivi doit s’arrêter.

Encapsuler les fonctions de rappel pour utiliser await

function getPosition(options) {
  return new Promise((resolve, reject) => {
    navigator.geolocation.getCurrentPosition(resolve, reject, options);
  });
}

async function useLocation() {
  if (!("geolocation" in navigator)) {
    showCityInput();
    return;
  }
  try {
    const { coords } = await getPosition({ timeout: 10000 });
    const url = new URL("https://api.example.com/weather");
    url.searchParams.set("lat", coords.latitude.toFixed(2));
    url.searchParams.set("lon", coords.longitude.toFixed(2));
    await loadWeather(url);
  } catch {
    showCityInput();
  }
}

Ici, showCityInput affiche la commande de saisie manuelle et loadWeather demande et affiche la météo. Relie useLocation au bouton de localisation. Le bloc catch couvre l’échec de localisation et la requête météo ; dans les deux cas, la saisie manuelle reste disponible.

Ne demander que la précision utile

Une position de latitude 52.3676, de longitude 4.9041 et de précision 35 a un rayon estimé d’environ 35 m. Arrondir à 52.37 et 4.90 réduit la précision envoyée au service météo. Un intervalle de latitude de 0,01° représente environ 1,1 km ; l’espacement des longitudes varie selon la latitude. Cette précision régionale convient à une prévision sans partager les coordonnées les plus détaillées.

Lorsque l’API Permissions est disponible, navigator.permissions.query({ name: "geolocation" }) indique "granted", "denied" ou "prompt". Détecte et gère aussi cette API. Son état aide à adapter l’interface, mais ne remplace pas la gestion des erreurs de l’appel de localisation.

L’API du presse-papiers permet à une page de copier du texte sans demander au lecteur de le sélectionner d’abord. Comme la géolocalisation, elle nécessite des vérifications de disponibilité, une action appropriée de l’utilisateur, une gestion des erreurs et une solution de repli.

Copier pendant le clic

navigator.clipboard.writeText(text) renvoie une promesse. Attends qu’elle soit tenue avant d’annoncer le succès. Un contexte sécurisé est obligatoire et une opération refusée peut entraîner un rejet avec NotAllowedError. Appelle cette méthode directement depuis un gestionnaire de clic : Firefox et Safari exigent une interaction récente de l’utilisateur, tandis que les exigences de Chromium peuvent aussi dépendre de l’autorisation d’écriture dans le presse-papiers.

copyButton.addEventListener("click", async () => {
  try {
    if (!navigator.clipboard?.writeText) {
      throw new Error("Copy unavailable");
    }
    await navigator.clipboard.writeText(codeField.value);
    copyButton.textContent = "Copied!";
  } catch {
    codeField.focus();
    codeField.select();
    copyButton.textContent = "Copy selected text: Ctrl+C / Cmd+C";
  }
  setTimeout(() => {
    copyButton.textContent = "Copy";
  }, 2000);
});

codeField est un champ de saisie ou une zone de texte et copyButton est le bouton de la page. Si la copie échoue, la sélection du texte permet de passer par le clavier : Ctrl+C sur de nombreux systèmes ou Cmd+C sur macOS. Le libellé redevient « Copy » après 2 000 ms. N’affiche jamais « Copied! » avant que la promesse soit tenue.

La lecture utilise navigator.clipboard.readText() et fait l’objet de contrôles plus stricts, car un presse-papiers peut contenir des données privées provenant d’autres applications. Un navigateur peut exiger une autorisation ou afficher une demande de collage. L’autorisation d’écrire ne garantit pas l’autorisation de lire.

Considérer la connectivité comme un indice

navigator.onLine et les événements online et offline de la fenêtre aident à afficher une bannière de connexion. Ils ne permettent pas de savoir si ton API est accessible. Un appareil peut avoir une connexion réseau alors que le serveur de l’API est en panne ou inaccessible.

window.addEventListener("offline", () => {
  status.textContent = "You are offline.";
});

Continue de gérer les erreurs autour de fetch même lorsque navigator.onLine est vrai. Utilise une région dynamique adaptée pour le message d’état.

Lire une recherche partageable

L’API URL lit la chaîne de requête de la page elle-même et construit aussi des URL d’API. Sur https://books.example.org/search?q=dune, new URL(location.href).searchParams.get("q") renvoie "dune". Lis cette valeur au chargement pour restaurer une recherche depuis un lien partagé. Un paramètre manquant renvoie null : décide donc de ce que l’écran initial doit afficher dans ce cas.

Utiliser une méthode d’apprentissage

Pour une autre API du navigateur, lis sa syntaxe, ses règles de contexte sécurisé et d’autorisation, son tableau de compatibilité et son statut Baseline sur MDN. Détecte ensuite la fonctionnalité, appelle-la depuis une action de l’utilisateur lorsque c’est nécessaire, traite sa promesse ou ses fonctions de rappel et propose une alternative si elle est absente ou refusée.

L’API Notifications affiche des notifications système après autorisation ; Web Share ouvre le menu de partage d’un appareil lorsqu’il est pris en charge ; Canvas dessine des graphismes ; les API multimédias contrôlent l’audio et la vidéo. Une API de cartographie tierce peut ajouter une bibliothèque et une clé de fournisseur. Ses identifiants suivent les mêmes règles concernant les clés secrètes que ceux de tout autre service. Tester un navigateur sur localhost ne prouve pas qu’un autre appareil ou navigateur dispose de la même prise en charge et du même contexte.