Fetch

Nous ne pouvons choisir qu’une seule méthode de lecture du corps.

Si nous avons déjà la réponse avec response.text(), alors response.json() ne fonctionnera pas, car le contenu du corps a déjà été traité.

let text = await response.text(); // corps de la réponse consommé
let parsed = await response.json(); // echec (déjà consommé)

En-têtes de réponse

Les en-têtes de réponse sont disponibles dans un objet d’en-têtes de type Map-like response.headers.

Ce n’est pas exactement un Map, mais il a des méthodes similaires pour obtenir des en-têtes individuels par nom ou les parcourir :

let response = await fetch('https://api.github.com/repos/javascript-tutorial/en.javascript.info/commits');

// get one header
alert(response.headers.get('Content-Type')); // application/json; charset=utf-8

// iterate over all headers
for (let [key, value] of response.headers) {
  alert(`${key} = ${value}`);
}

En-têtes de requêtes

Pour définir un en-tête de requête dans fetch, nous pouvons utiliser l’option headers. Il a un objet avec des en-têtes sortants, comme ceci :

let response = fetch(protectedUrl, {
  headers: {
    Authentication: 'secret'
  }
});

… Mais il y a une liste d’en-têtes HTTP interdits que nous ne pouvons pas définir :

• Accept-Charset, Accept-Encoding
• Access-Control-Request-Headers
• Access-Control-Request-Method
• Connection
• Content-Length
• Cookie, Cookie2
• Date
• DNT
• Expect
• Host
• Keep-Alive
• Origin
• Referer
• TE
• Trailer
• Transfer-Encoding
• Upgrade
• Via
• Proxy-*
• Sec-*

Ces en-têtes assurent un HTTP correct et sûr, ils sont donc contrôlés exclusivement par le navigateur.

Requêtes POST

Pour faire une requête POST, ou une requête avec une autre méthode, nous devons utiliser les options fetch :

• method – HTTP-method, par exemple POST,
• body – le corps de la requête, un parmi ceux-ci :
  • une chaîne de caractères (par exemple encodé en JSON),
  • un objet FormData, pour soumettre les données en tant que multipart/form-data,
  • Blob/BufferSource pour envoyer des données binaires,
  • URLSearchParams, pour soumettre les données au format x-www-form-urlencoded, rarement utilisé.

Le format JSON est utilisé la plupart du temps.

Par exemple, ce code soumet l’objet user en JSON :

let user = {
  name: 'John',
  surname: 'Smith'
};

let response = await fetch('/article/fetch/post/user', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json;charset=utf-8'
  },
  body: JSON.stringify(user)
});

let result = await response.json();
alert(result.message);

Veuillez noter que si la requête body est une chaîne de caractères, alors l’en-tête Content-Type est défini sur text/plain;charset=UTF-8 par défaut.

Mais, si nous envoyons du JSON, nous utiliserons à la place l’option headers pour envoyer application/json, le bon Content-Type pour les données encodées en JSON.

Envoi d’une image

Nous pouvons également soumettre des données binaires avec fetch en utilisant des objets Blob ou BufferSource.

Dans cet exemple, il y a un <canvas> où nous pouvons dessiner en déplaçant une souris dessus. Un clic sur le bouton “submit” envoie l’image au serveur :

<body style="margin:0">
  <canvas id="canvasElem" width="100" height="80" style="border:1px solid"></canvas>

  <input type="button" value="Submit" onclick="submit()">

  <script>
    canvasElem.onmousemove = function(e) {
      let ctx = canvasElem.getContext('2d');
      ctx.lineTo(e.clientX, e.clientY);
      ctx.stroke();
    };

    async function submit() {
      let blob = await new Promise(resolve => canvasElem.toBlob(resolve, 'image/png'));
      let response = await fetch('/article/fetch/post/image', {
        method: 'POST',
        body: blob
      });

      // le serveur répond avec confirmation et la taille de l'image
      let result = await response.json();
      alert(result.message);
    }

  </script>
</body>

Veuillez noter qu’ici, nous ne définissons pas l’en-tête Content-Type manuellement, car un objet Blob a un type intégré (ici image/png, tel que généré par toBlob). Pour les objets Blob, ce type devient la valeur de Content-Type.

La fonction submit() peut être réécrite sans async/await comme ceci :

function submit() {
  canvasElem.toBlob(function(blob) {
    fetch('/article/fetch/post/image', {
      method: 'POST',
      body: blob
    })
      .then(response => response.json())
      .then(result => alert(JSON.stringify(result, null, 2)))
  }, 'image/png');
}

Résumé

Une requête fetch typique se compose de deux appels await :

let response = await fetch(url, options); // se résout avec des en-têtes de réponse
let result = await response.json(); // lit le corps en tant que JSON

Ou, sans await :

fetch(url, options)
  .then(response => response.json())
  .then(result => /* process result */)

Propriétés de réponse :

• response.status – Code HTTP de la réponse,
• response.ok – true est le statut 200-299.
• response.headers – objet Map-like avec en-têtes HTTP.

Méthodes pour obtenir le corps de réponse :

• response.text() – retourne la réponse sous forme de texte,
• response.json() – analyse la réponse en tant qu’objet JSON,
• response.formData() – retourne la réponse en tant qu’objet FormData (encodage multipart/form-data, voir le chapitre suivant),
• response.blob() – retourne la réponse en tant que Blob (données binaires avec type),
• response.arrayBuffer() – retourne la réponse en tant que ArrayBuffer (données binaires de bas niveau),

Options de fetch jusque là :

• method – Méthode HTTP,
• headers – un objet avec en-têtes de requête (aucun en-tête n’est autorisé),
• body – les données à envoyer (corps de la demande) en tant que string, FormData, BufferSource, Blob ou objet UrlSearchParams.

Dans les chapitres suivants, nous verrons plus d’options et de cas d’utilisation de fetch.