API Fetch

Objectifs

  • Découvrir les atouts de API Fetch

  • Savoir utiliser API Fetch

Mise en situation

ES6 apporte bon nombre d'évolutions majeures à JavaScript, notamment les promesses. Avant ES6, les requêtes HTTP étaient faites à l'aide de l'objet XmlHttpRequest, au prix d'une configuration assez lourde, avec beaucoup de code à écrire et un imbrication de callbacks, possible source d'erreur.

API Fetch est une interface JavaScript qui va nous permettre de profiter des avancées des promesses pour simplifier nos requêtes HTTP.

MéthodeUtilisation de API Fetch

Créer une requête avec API Fetch est assez simple et rapide. Il suffit d'utiliser la méthode .fetch() qui attend une URL en paramètre et qui retourne une Promise.

Si la requête est exécutée avec succès, la Promise sera fulfilled, sinon elle sera rejected. La méthode .resolve() sera appelée avec la réponse en paramètre.

Par défaut, le verbe HTTP utilisé est GET.

1
fetch('http://mon-serveur/ma-ressource')
2
    .then((response) => console.log(response));

La méthode .fetch() a un second paramètre optionnel qui va permettre de passer la configuration à l'API.

Ce second paramètre (init) attend un objet JavaScript avec des propriétés comme le verbe HTTP, les headers, le body de la requête si besoin, etc.

1
var myInit = { method: 'GET',
2
               headers: { "Content-Type": "text/plain;charset=UTF-8",
3
                          "Content-Encoding": "gzip"
4
                        }, //On pourra aussi utiliser l'objet Headers
5
               mode: 'cors', // Permet les requêtes cross-origin - aussi mode par défaut
6
               cache: 'default' }; // contrôle la manière dont la requête interagira avec le cache HTTP du navigateur
7
8
fetch('http://mon-serveur/ma-ressource', myInit)
9
    .then((response) => console.log(response));
MéthodeEnvoyer des données avec API Fetch : la méthode POST
Le POST avec API Fetch est très similaire au GET, à cela près que la requête va avoir un paramètre supplémentaire body correspondant aux données que l'on souhaite envoyer.
1
const headers = new Headers();
2
const body = JSON.stringify({
3
    firstname: 'David',
4
    lastname: 'Marty',
5
    position: 'Outside center'
6
}); //JSON.stringify pour convertir en objet JSON et éviter le risque des caractères spéciaux.
7
8
const init = { 
9
    method: 'POST',
10
    headers: headers,
11
    body: body };
12
13
fetch('http://mon-serveur/players', init)
14
    .then((response) => console.log(response));
Le body d'un POST avec API Fetch pourra aussi être un objet FormData.
1
const headers = new Headers();
2
const body = new FormData();
3
/*[...] Ajout de valeurs au FormData [...]*/
4
const init = { 
5
    method: 'POST',
6
    headers: headers,
7
    body: body };
8
9
fetch('http://mon-serveur/players', init)
10
    .then((response) => console.log(response));
MéthodeAPI Fetch et JSON
L'API Fetch permet d'effectuer une requête asynchrone vers une ressource fournie par un serveur, et de récupérer un objet JavaScript à partir des résultats obtenus lors de l'appel. Cela signifie que cette API propose une méthode similaire à JSON.parse(), nativement présente en JavaScript, à la différence que les données obtenues via Fetch seront lues et transformées dans un type JavaScript, de manière asynchrone
Pour obtenir un type JavaScript valide suite à un appel via l'API Fetch, il faut utiliser la fonction .json(). Celle-ci retourne une promesse contenant le type JavaScript correspondant à la représentation structurée des résultats en JSON.
Exemple
1
fetch("https://www.data.gouv.fr/api/1/activity?page=1&page_size=20")
2
	.then(response => {
3
		return response.json();
4
	})
5
	.then(response => {
6
		console.log(response)
7
	})
8
	.catch(error => alert("Erreur : " + error));
Lorsque ce code s'exécute, un appel asynchrone est réalisé par l'API Fetch vers l'URL « https://www.data.gouv.fr/api/1/activity?page=1&page_size=20 ». Cela se matérialise par une promesse qui contient des données au format JSON.
À la résolution de cette promesse, l'appel à response.json() va transformer de manière asynchrone les résultats en un objet JavaScript à travers une nouvelle promesse, dont la résolution permet d'afficher l'objet final dans la console du navigateur.
Attention
Il existe différents formalismes de données, même si JSON est le format le plus populaire sur le Web. Il faut donc impérativement s'assurer du format obtenu lors de la récupération des données. Ainsi, afin de s'assurer de la bonne utilisation de la fonction .json(), il est nécessaire que la ressource contactée soit au bon format Il est en effet courant que les services mis à disposition sur le Web proposent différents formalismes de données définissables lors de l'appel.
Dans certains cas, cela se matérialise par l'ajout du paramètre format=json ou du header de requête Accept. Afin de savoir comme spécifier un format, il est nécessaire de consulter la documentation du service ciblé avant de commencer les développements.
SyntaxeÀ retenir
  • API Fetch permet de configurer et d'envoyer des requêtes HTTP beaucoup plus simplement que l'ancien objet XmlHttpRequest.
  • API Fetch s'appuie sur le puissant mécanisme des Promises pour faciliter le traitement.
  • L'API Fetch expose une fonction .json() permettant d'obtenir de manière asynchrone un type JavaScript correspondant aux données JSON retournées par la ressource contactée.
  • Afin d'utiliser cette fonctionnalité, il est nécessaire de s'assurer au préalable que la ressource ciblée fournit des données au format JSON, en consultant sa documentation.