Solicitações HTTP em Node.js com a API Fetch

A API Fetch representa a nova forma oficialmente suportada de realizar solicitações HTTP e recuperar recursos locais em Node.js. Isso significa que você não precisa mais de dependências externas do cliente HTTP em seu projeto. Tudo o que você precisa fazer é aprender a usar a API Node Fetch, que é a essência deste guia.

Aqui, você verá:

• O que é a API Fetch
• Começando com a API Node Fetch
• Fazendo solicitações HTTP em Node.js com a API Fetch
• Opções e recursos extras

Vamos lá!

O que é a API Fetch?

A API Fetch é uma interface JavaScript para buscar recursos localmente ou em uma rede. Em detalhes, ele fornece uma função global fetch() que facilita a execução de solicitações HTTP assíncronas. O mesmo método também pode ser usado para recuperar arquivos locais. A API JavaScript Fetch é um substituto flexível para a antiga API XMLHttpRequest.

O método fetch() é baseado nos objetos Request e Response. Ele requer apenas um argumento obrigatório, o caminho local ou URL para o recurso que você deseja buscar. Ele também aceita algumas opções opcionais, incluindo CORS, cabeçalho HTTP e configurações de cache. Como um método assíncrono, o fetch() retorna uma Promise que resolve a resposta produzida pelo servidor. Isso é representado por um objeto Response , que expõe vários métodos para acessar e analisar o corpo do conteúdo.

Esta é a aparência de uma chamada básica da API Fetch:

fetch("https://httpbin.io/ip", {

  // optional configs...

}).then((response) => {

  // print the JSON response body

  console.log(response.json()) // {  "origin": "<YOUR_IP_ADDRESS>" }

})

Or if you prefer the equivalent async/await syntax, you can write:

const response = await fetch("https://httpbin.io/ip", {

  // optional configs...

})

// print the JSON response body

console.log(await response.json()) // { "origin": "<YOUR_IP_ADDRESS>" }

Começando a usar a API Node Fetch

A API Fetch é suportada pelos principais navegadores há anos. No entanto, ela só faz parte da biblioteca padrão do Node.js desde a versão 18.0.0, lançada em abril de 2022. Especificamente, a API Node Fetch é baseada na implementação da undici.

Antes do Node.js 18, você podia usar o fetch() habilitando-o como um recurso experimental ou graças à biblioteca node-fetch npm, outra implementação popular da API Fetch. Como o fetch() agora faz parte da biblioteca padrão oficial do Node.js, você pode usá-lo diretamente no seu código sem importá-lo. Tudo o que você precisa fazer é chamar o método fetch() com a sintaxe abaixo:

fetch(url, options)

O URL é obrigatório e pode conter:

• O caminho para um recurso local (ex.: movies.json) 
• O URL para um endpoint ou recurso remoto ex.: https://httpbin.io/ip ou https://example.com/movies.json)

Por outro lado, options é um objeto opcional que aceita os seguintes campos opcionais:

• method: o método HTTP da solicitação, como “GET”, “POST”, “PUT”, “PATCH” e “DELETE”. O padrão é definido como “GET”. 
• headers: um cabeçalho ou literal de objeto contendo os cabeçalhos HTTP a serem adicionados à sua solicitação. Por padrão, nenhum cabeçalho é definido.
• body: o objeto que contém os dados a serem usados como corpo da sua solicitação. Note que as solicitações GET e HEAD não podem ter um corpo.
• mode: o modo a ser usado para a solicitação (por exemplo, “cors”, “no-cors”, “same-origin”, “navigate” ou “websocket”). O padrão é definido como cors.
• credentials: para especificar se o navegador deve ou não enviar as credenciais. Deve ser uma das seguintes sequências de caracteres: “omit”, “same-origin” ou “include”.
• redirect: para determinar como lidar com uma resposta de redirecionamento HTTP. Pode ser “follow”, “error” ou “manual”. O padrão é definido como “follow”.
• referrer: Uma string contendo o referenciador da solicitação. Por padrão, é uma string vazia.
• ReferrerPolicy: especifica a política de referência a ser usada na solicitação.
• signal: uma instância do objeto AbortSignal que permite abortar a solicitação por meio da interface AbortController.
• priority: uma string que especifica a prioridade da solicitação Fetch atual em relação a outras solicitações do mesmo tipo. Ela aceita os as opções “high”, “low” ou “auto”. O padrão é “auto”.

Confira a seção de parâmetrosfetch() da documentação oficial para saber mais.

Este é um exemplo de uma solicitação de busca do Node.js com um objeto de opções:

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",

  }),

})

Observe que os dados do corpo devem corresponder ao cabeçalho Content-Type.

Fazendo solicitações HTTP em Node.js com a API Fetch

Agora, vamos ver a API Node Fetch em ação em exemplos de solicitações reais para os métodos HTTP mais populares.

GET

É assim que você pode realizar uma solicitação GET com a API Fetch:

const response = await fetch("https://your-domain.com/your-endpoint")

Como você pode ver, é necessária apenas uma linha de código. Isso ocorre porque o fetch() executa solicitações GET por padrão.

Em seguida, você pode acessar o conteúdo da resposta com um dos métodos abaixo:

• response.text(): retorna uma promessa que é resolvida com o corpo da resposta como texto.
• response.json(): retorna uma promessa que é resolvida com um objeto analisado a partir da resposta JSON.
• response.blob(): retorna uma promessa que é resolvida com o corpo da resposta como um objeto Blob.
• response.arrayBuffer(): retorna uma promessa que é resolvida com o corpo da resposta como uma instância de ArrayBuffer.
• response.formData(): retorna uma promessa que é resolvida com o corpo da resposta como um objeto FormData.

Então, o código de um exemplo completo seria:

const response = await fetch("https://httpbin.io/ip")

const jsonResponseContent = await response.json() // { "origin": "<YOUR_IP_ADDRESS>" }

const origin = jsonResponseContent.origin // <YOUR_IP_ADDRESS>

Se a resposta retornada pelo servidor não estiver no formato JSON, a instrução response.json() falhará com um SyntaxError.

POST

Fazer uma solicitação POST com uma chamada à API Node Fetch leva apenas algumas linhas:

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,

})

A chave para enviar uma solicitação POST com fetch() é especificar os dados a serem enviados ao servidor na opção body. Isso pode ser feito em vários formatos, incluindo JSON, FormData e texto. Ao enviar um objeto FormData, você não precisa especificar um cabeçalho Content-Type. Caso contrário, é obrigatório especificar. 

PUT

Executar uma solicitação PUT com a API Fetch é um processo semelhante ao de fazer um 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",

  }),

})

A única diferença é que você precisa especificar “PUT” como configuração do método. Da mesma forma, você pode enviar uma solicitação PATCH definindo-a como “PATCH”.

DELETE

Aqui está um exemplo de uma solicitação HTTP DELETE com o fetch():

const response = await fetch("https://example.com/api/v1/users/45", {

  method: "DELETE",

})

Novamente, tudo se resume a definir o método HTTP correto. A implementação da API Fetch cuidará do resto.

Opções e recursos extras

Agora que você sabe como usar o fetch() em cenários comuns, está pronto(a) para explorar as opções avançadas da API Node Fetch.

Configurando cabeçalhos

O fetch() permite que você personalize os cabeçalhos HTTP da sua solicitação por meio do campo de cabeçalhos do objeto de opções. Em particular, é possível usar um objeto Headers ou um objeto literal com valores de string específicos no cabeçalho.

Suponha que você queira definir o cabeçalho Content-Type e User-Agent em sua solicitação fetch(). Você pode usar um objeto Headers conforme abaixo:

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,

  // other options...

})

Caso contrário, você poderia defini-los de forma equivalente com um objeto literal:

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",

  },

  // other options...

})

Essa sintaxe é mais compacta e fácil de ler.

Lendo cabeçalhos

Se você quiser ler os cabeçalhos HTTP definidos pelo servidor na resposta, você pode acessá-los da seguinte forma:

const response = await fetch("https://your-domain.com/your-endpoint", {

  // optional configs...

})

// accessing the "Content-Type" response header

const responseHeaders = response.headers

const responseContentType = response.headers.get("Content-Type")

O campo response.headers retorna um objeto Headers, a partir do qual você pode acessar cabeçalhos específicos com o método get().

Tratamento de erros da API Node Fetch

Uma chamada da API Node.js Fetch só pode falhar por dois motivos:

• Uma exceção AbortError: quando a solicitação foi intencionalmente abortada por um AbortController.
• Uma exceção TypeError: isso pode ocorrer por vários motivos, como um nome de cabeçalho inválido, um URL inválido ou um erro genérico de rede. Descubra mais causas nos documentos.

O que é essencial entender é que qualquer resposta 4xx ou 5xx é considerada uma solicitação bem-sucedida para a API Fetch. Em outras palavras, uma resposta de erro produzida pelo servidor não acionará nenhum erro de JavaScript. O motivo desse comportamento é que o fetch() fez a solicitação e o servidor deu uma resposta. Conceitualmente, isso não pode ser considerado um erro do ponto de vista da rede. No fim das contas, a solicitação terminou com sucesso.

Isso significa que, antes de lidar com os dados retornados pelo servidor, você deve sempre verificar se uma resposta foi bem-sucedida. Para fazer isso, você pode implementar a lógica de tratamento de erros abaixo:

try {

  const response = await fetch("https://your-domain.com/your-endpoint", {

    // optional configs...

  })

  if (response.ok) {

    // use the data returned by the server...

    // e.g., 

    // await response.json()

  } else {

    // handle 4xx and 5xx errors...

  }

} catch (error) {

  // handle network or abort errors...

}

Observe que a propriedade ok do Response só contém a resposta true quando a solicitação é bem-sucedida.

Cancelando uma solicitação Fetch

A API Fetch suporta a interrupção de solicitações já iniciadas por meio da API AbortController. 

Para interromper uma solicitação fetch() em andamento, primeiro você precisa gerar um objeto de sinal conforme abaixo:

const controller = new AbortController()

const signal = controller.signal

Then, specify it in the options object of your request:

const response = await fetch("https://your-domain.com/your-endpoint", {

  signal: signal,

  // other configs...

})

Agora, sempre que você chamar a seguinte instrução, sua solicitação será interrompida por um AbortError:

controller.abort()

Lembre-se de que o servidor pode já ter recebido a solicitação. Nesse caso, o servidor ainda executará a solicitação, mas a resposta será ignorada pelo Node.js.

Parabéns! Agora você é mestre da API Node.js Fetch!

Conclusão

Neste artigo, você aprendeu o que é a API Fetch e como usá-la no Node.js. Em detalhes, você começou com o básico do fetch() e depois se aprofundou em suas opções e recursos avançados. Com um cliente HTTP tão poderoso, a recuperação de dados on-line se torna fácil. Por exemplo, você pode usar esse método para chamar nossos terminais SERP API e começar a coletar dados SERP.

A Bright Data é a maior plataforma de dados da Web do mundo, atendendo a mais de 20.000 empresas em todo o mundo. Converse com um de nossos especialistas em dados para encontrar o produto certo para você e suas necessidades de coleta de dados.