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(u0022https://httpbin.io/ipu0022, {nn  // optional configs...nn}).then((response) =u003e {nn  // print the JSON response bodynn  console.log(response.json()) // {  u0022originu0022: u0022u003cYOUR_IP_ADDRESSu003eu0022 }nn})nnOr if you prefer the equivalent async/await syntax, you can write:nnconst response = await fetch(u0022https://httpbin.io/ipu0022, {nn  // optional configs...nn})nn// print the JSON response bodynnconsole.log(await response.json()) // { u0022originu0022: u0022u003cYOUR_IP_ADDRESSu003eu0022 }n

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(u0022https://your-domain.com/api/v1/usersu0022, {nn  method: u0022POSTu0022,nn  credentials: u0022includeu0022,nn  headers: {nn    u0022Content-Typeu0022: u0022application/jsonu0022,nn  },nn  body: JSON.stringify({nn    username: u0022jane-doeu0022,nn    email: [email protected]    role: u0022superuseru0022,nn    age: 23,nn    birthplace: u0022New Yorku0022,nn  }),nn})n

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(u0022https://your-domain.com/your-endpointu0022)const response = await fetch(u0022https://your-domain.com/your-endpointu0022)

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(u0022https://httpbin.io/ipu0022)nnconst jsonResponseContent = await response.json() // { u0022originu0022: u0022u003cYOUR_IP_ADDRESSu003eu0022 }nnconst origin = jsonResponseContent.origin // u003cYOUR_IP_ADDRESSu003e

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()nnformData.append(u0022usernameu0022, u0022serena-smithu0022)nnformData.append(u0022emailu0022, [email protected])nnconst response = await fetch(u0022https://example.com/api/v1/usersu0022, {nn  method: u0022POSTu0022,nn  body: formData,nn})

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(u0022https://example.com/api/v1/usersu0022, {nn  method: u0022PUTu0022,nn  credentials: u0022includeu0022,nn  headers: {nn    u0022Content-Typeu0022: u0022application/jsonu0022,nn  },nn  body: JSON.stringify({nn    username: u0022john-doeu0022,nn    email: [email protected]    role: u0022regular-useru0022,nn    age: 47,nn    birthplace: u0022Chicagou0022,nn  }),nn})n

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(u0022https://example.com/api/v1/users/45u0022, {nn  method: u0022DELETEu0022,nn})

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()nncustomHeaders.append(u0022Content-Typeu0022, u0022application/jsonu0022)nncustomHeaders.append(u0022User-Agentu0022, u0022Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36u0022)nnconst response = fetch(u0022https://your-domain.com/your-endpointu0022, {nn  headers: customHeaders,nn  // other options...nn})

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

  const response = fetch(u0022https://your-domain.com/your-endpointu0022, {nn  headers: {nn    u0022Content-Typeu0022: u0022application/jsonu0022,nn    u0022User-Agentu0022: u0022Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36u0022,nn  },nn  // other options...nn})

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(u0022https://your-domain.com/your-endpointu0022, {nn  // optional configs...nn})nn// accessing the u0022Content-Typeu0022 response headernnconst responseHeaders = response.headersnnconst responseContentType = response.headers.get(u0022Content-Typeu0022)

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 {nn  const response = await fetch(u0022https://your-domain.com/your-endpointu0022, {nn    // optional configs...nn  })nn  if (response.ok) {nn    // use the data returned by the server...nn    // e.g., nn    // await response.json()nn  } else {nn    // handle 4xx and 5xx errors...nn  }nn} catch (error) {nn  // handle network or abort errors...nn}n

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()nnconst signal = controller.signalnnThen, specify it in the options object of your request:nnconst response = await fetch(u0022https://your-domain.com/your-endpointu0022, {nn  signal: signal,nn  // other configs...nn})

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

  controller.abort()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.