L’API Fetch représente le nouveau moyen officiellement pris en charge pour créer des requêtes HTTP et récupérer des ressources locales dans Node.js. Cela signifie que vous n’avez plus besoin de dépendances client HTTP externes dans votre projet. Il vous suffit d’apprendre à utiliser l’API Node Fetch, ce qui est l’objet de ce guide.
Ici, vous allez apprendre :
- Ce qu’est l’API Fetch
- Démarrer avec l’API Node Fetch
- Créer des requêtes HTTP dans Node.js avec l’API Fetch
- Les options et fonctionnalités supplémentaires
C’est parti !
Qu’est-ce que l’API Fetch ?
L’API Fetch est une interface JavaScript permettant de récupérer des ressources localement ou sur un réseau. En détail, elle fournit une fonction globale fetch() qui facilite la création de requêtes HTTP asynchrones. La même méthode peut également être utilisée pour récupérer des fichiers locaux. L’API JavaScript Fetch est une solution flexible de remplacer l’ancienne API XMLHttpRequest.
La méthode fetch() est basée sur les objets Request et Response. Elle ne requiert qu’un seul argument obligatoire, le chemin local ou l’URL de la ressource que vous souhaitez récupérer. Elle accepte également plusieurs options facultatives, notamment CORS, l’en-tête HTTP et les paramètres de mise en cache. En tant que méthode asynchrone, fetch() renvoie une Promise qui résout la réponse produite par le serveur. Celle-ci est représentée par un objet Response, qui expose plusieurs méthodes permettant d’accéder à son contenu et de l’analyser.
Voici à quoi ressemble un appel de base avec l’API Fetch :
fetch("https://httpbin.io/ip", {
// Configurations facultatives...
}).then((response) => {
// affiche le corps de la réponse JSON
console.log(response.json()) // { "origin": "<VOTRE_ADRESSE_IP>" }
})
Ou si vous préférez la syntaxe asynchrone/await équivalente, vous pouvez écrire :
const response = await fetch("https://httpbin.io/ip", {
// Configurations facultatives...
})
// affice le corps de la réponse JSON
console.log(await response.json()) // { "origin": "<VOTRE_ADRESSE_IP>" }
Démarrer avec l’API Node Fetch
L’API Fetch est prise en charge par les principaux navigateurs depuis des années. Pourtant, elle ne fait partie de la bibliothèque standard Node.js que depuis la version 18.0.0, publiée en avril 2022. Plus précisément, l’API Node Fetch est basée sur l’implémentation d’undici.
Avant Node.js 18, vous pouviez utiliser fetch() en l’activant en tant que fonctionnalité expérimentale ou grâce à la bibliothèque node-fetch npm, une autre implémentation populaire de l’API Fetch. Depuis que fetch() fait partie de la bibliothèque standard officielle de Node.js, vous pouvez l’utiliser directement dans votre code sans l’importer. Il vous suffit d’appeler la méthode fetch() avec la syntaxe ci-dessous :
fetch(url, options)
« url » est obligatoire et peut contenir :
- Le chemin vers une ressource locale (par exemple, movies.json)
- L’URL d’un point de terminaison ou d’une ressource distante (par exemple, https://httpbin.io/ip ou https://example.com/movies.json).
options est un objet facultatif qui accepte les champs optionnels suivants :
- méthode : la méthode HTTP de la requête, telle que « GET », « POST », « PUT », « PATCH » et « DELETE ». La valeur par défaut est « GET ».
- headers : un littéral d’en-tête ou d’objet contenant les en-têtes HTTP à ajouter à votre requête. Par défaut, aucun en-tête n’est défini.
- body : l’objet contenant les données à utiliser comme corps de votre requête. Notez que les requêtes GET et HEAD ne peuvent pas avoir de corps.
- mode : le mode à utiliser pour la requête (par exemple, « cors », « no-cors », « same-origin », « navigate » ou « websocket »). La valeur par défaut est « cors ».
- credentials : indique si le navigateur doit envoyer les informations d’identification ou non. Il doit s’agir de l’une des chaînes suivantes : « omit », « same-origin » ou « include ».
- redirect : détermine la manière de gérer une réponse de redirection HTTP. Il peut s’agir de « follow », « error » ou « manual ». La valeur par défaut est « follow ».
- referrer : une chaîne contenant le référent de la requête. Par défaut, il s’agit d’une chaîne vide.
- referrerPolicy : spécifie la politique de référencement à utiliser pour la demande.
- signal : une instance d’objet AbortSignal qui vous permet d’interrompre la demande via l’interface AbortController.
- priority : chaîne de caractères indiquant la priorité de la requête Fetch en cours par rapport aux autres requêtes du même type. Valeurs possibles : « high », « low » ou « auto ». La valeur par défaut est « auto ».
Consultez la section sur les paramètres de fetch() dans la documentation officielle pour en savoir plus.
Voici un exemple de requête Node.js Fetch avec un objet options :
const response = await fetch("https://your-domain.com/api/v1/users", {
method: "POST",
credentials: "include",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
username: "jane-doe",
email: "[email protected]"
role: "superuser",
age: 23,
birthplace: "New York",
}),
})
Notez que les données du corps doivent correspondre à l’en-tête Content-Type.
Création de requêtes HTTP dans Node.js avec l’API Fetch
Voyons maintenant l’API Fetch de Node en action dans des exemples de requêtes du monde réel pour les méthodes HTTP les plus populaires.
GET
Voici comment créer une requête GET avec l’API Fetch :
const response = await fetch("https://your-domain.com/your-endpoint")
Comme vous pouvez le constater, il suffit d’une seule ligne de code. En effet, fetch() exécute les requêtes GET par défaut.
Vous pouvez ensuite accéder au contenu de la réponse à l’aide de l’une des méthodes ci-dessous :
- response.text() : renvoie une promesse qui contient le corps de la réponse sous forme de texte.
- response.json() : renvoie une promesse qui se résout avec un objet analysé à partir de la réponse JSON.
- response.blob() : renvoie une promesse qui se résout avec le corps de la réponse en tant qu’objet Blob.
- response.arrayBuffer() : renvoie une promesse qui se résout avec le corps de la réponse en tant qu’instance ArrayBuffer.
- response.formData() : renvoie une promesse qui se résout avec le corps de la réponse sous la forme d’un objet FormData.
Voici un exemple de code complet :
const response = await fetch("https://httpbin.io/ip")
const jsonResponseContent = await response.json() // { "origin": "<VOTRE_ADRESSE_IP>" }
const origin = jsonResponseContent.origin // <VOTRE_ADRESSE_IP>
Si la réponse renvoyée par le serveur n’est pas au format JSON, l’instruction response.json() échouera avec une SyntaxError.
POST
Il ne faut que quelques lignes pour créer une requête POST avec un appel API Node Fetch :
const formData = new FormData()
formData.append("username", "serena-smith")
formData.append("email", "[email protected]")
const response = await fetch("https://example.com/api/v1/users", {
method: "POST",
body: formData,
})
Le principal lorsque vous envoyez une requête POST avec fetch(), c’est de spécifier les données à envoyer au serveur dans l’option « body ». Ces données peuvent se présenter sous plusieurs formats, notamment JSON, FormData et texte. Lorsque vous envoyez un objet FormData, vous n’avez pas besoin de spécifier un en-tête Content-Type. Dans le cas contraire, il est obligatoire.
PUT
L’exécution d’une requête PUT avec l’API Fetch est identique à celle d’une requête POST :
const response = await fetch("https://example.com/api/v1/users", {
method: "PUT",
credentials: "include",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
username: "john-doe",
email: "[email protected]"
role: "regular-user",
age: 47,
birthplace: "Chicago",
}),
})
La seule différence, c’est que vous devez indiquer « PUT » comme type de méthode. De même, vous pouvez envoyer une requête PATCH en indiquant « PATCH ».
DELETE
Voici un exemple de requête HTTP DELETE avec fetch() :
const response = await fetch("https://example.com/api/v1/users/45", {
method: "DELETE",
})
Une fois encore, il s’agit de définir la bonne méthode HTTP. L’implémentation de l’API Fetch s’occupe du reste.
Options et fonctionnalités supplémentaires
Maintenant que vous savez comment utiliser fetch() dans des scénarios courants, vous êtes prêt à explorer les options avancées de l’API Fetch de Node.
Définition des en-têtes
fetch() vous permet de personnaliser les en-têtes HTTP de votre requête grâce au champ headers de l’objet options. Le paramètre headers accepte un objet Headers ou un objet littéral avec des valeurs de chaîne spécifiques.
Supposons que vous souhaitiez définir les en-têtes Content-Type et User-Agent dans votre requête fetch(). Vous pouvez utiliser un objet Headers comme indiqué ci-dessous :
const customHeaders = new Headers()
customHeaders.append("Content-Type", "application/json")
customHeaders.append("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36")
const response = fetch("https://your-domain.com/your-endpoint", {
headers: customHeaders,
// Autres options...
})
Sinon, vous pouvez les définir de manière équivalente avec un objet littéral :
const response = fetch("https://your-domain.com/your-endpoint", {
headers: {
"Content-Type": "application/json",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
},
// Autres options...
})
Cette syntaxe est plus compacte et plus facile à lire.
Lecture des en-têtes
Si vous souhaitez lire les en-têtes HTTP définis par le serveur dans la réponse, vous pouvez y accéder comme suit :
const response = await fetch("https://your-domain.com/your-endpoint", {
// Configurations facultatives...
})
// Accès à l’en-tête de réponse « Content-Type »
const responseHeaders = response.headers
const responseContentType = response.headers.get("Content-Type")
Le champ response.headers renvoie un objet Headers, à partir duquel vous pouvez accéder à des en-têtes spécifiques à l’aide de la méthode get().
Gestion des erreurs de l’API Node Fetch
Un appel à l’API Node.js Fetch ne peut échouer que pour deux raisons :
- Une exception AbortError : lorsque la demande a été intentionnellement interrompue par un AbortController.
- Une exception TypeError : cela peut se produire pour plusieurs raisons, telles qu’un nom d’en-tête invalide, une URL invalide ou une erreur réseau générique. Pour en savoir plus sur les causes possibles, consultez la documentation.
Il est essentiel de comprendre que toute réponse 4xx ou 5xx est considérée comme une demande réussie pour l’API Fetch. En d’autres termes, si le serveur renvoie une erreur, cela ne déclenchera aucune erreur JavaScript. En effet, fetch() a envoyé la requête et le serveur lui a bien répondu. Conceptuellement, cela ne peut pas être considéré comme une erreur du point de vue du réseau. En fin de compte, la requête s’est terminée avec succès.
Cela signifie qu’avant de traiter les données renvoyées par le serveur, vous devez toujours vérifier si la réponse est positive. Pour ce faire, vous pouvez mettre en œuvre la logique de gestion des erreurs ci-dessous :
try {
const response = await fetch("https://your-domain.com/your-endpoint", {
// Configurations facultatives...
})
if (response.ok) {
// utiliser les données renvoyées par le serveur...
// par exemple,
// await response.json()
} else {
// gérer les erreurs 4xx et 5xx...
}
} catch (error) {
//gérer les erreurs de réseau ou d’abandon...
}
Notez que la propriété « ok » de Response ne contient « true » que lorsque la requête a abouti.
Abandon d’une requête Fetch
L’API Fetch prend en charge l’interruption des requêtes déjà lancées par l’intermédiaire de l’API AbortController.
Pour arrêter une requête fetch() en cours, vous devez d’abord générer un objet signal comme ci-dessous :
const controller = new AbortController()
const signal = controller.signal
Ensuite, spécifiez-le dans l’objet options de votre requête :
const response = await fetch("https://your-domain.com/your-endpoint", {
signal: signal,
// Autres configurations...
})
Désormais, chaque fois que vous appellerez l’instruction suivante, votre requête sera interrompue par un AbortError :
controller.abort()
N’oubliez pas que le serveur peut avoir déjà reçu la demande. Dans ce cas, le serveur exécutera quand même la requête, mais la réponse sera ignorée par Node.js.
Félicitations ! Vous maîtrisez désormais l’API Fetch de Node.js !
Conclusion
Dans cet article, vous avez appris ce qu’est l’API Fetch et comment l’utiliser dans Node.js. En détail, vous avez commencé par les bases de fetch(), puis nous avons détaillé ses options et fonctionnalités avancées. Avec un client HTTP aussi puissant, il devient facile de récupérer des données en ligne. Par exemple, vous pouvez l’utiliser pour appeler nos points d’extrémité SERP API et commencer à récupérer des données SERP.
Bright Data est la plus grande plateforme de données web au monde, au service de plus de 20 000 entreprises dans le monde entier. Contactez l’un de nos experts en données pour trouver le produit qui répond le mieux à vos besoins en matière de récupération de données web.
