Fetch e APIs do navegador: busca de dados

Uma API web permite que um programa leia ou altere dados por meio de URLs identificadas chamadas pontos de acesso da API. O JavaScript na página é o cliente. Ele envia uma requisição HTTP; o servidor responde com uma resposta HTTP. Muitas APIs enviam texto JSON, que pode representar objetos, vetores, cadeias de caracteres, números, booleanos e null.

Ler uma requisição

Considere GET https://api.example.com/books?author=Le%20Guin&limit=5. O método é GET, o caminho /books seleciona o recurso e a cadeia de consulta contém dois parâmetros. O valor de author é “Le Guin”; %20 codifica o espaço. Um e comercial separa os parâmetros. A documentação da API explica quais nomes de parâmetros ela aceita e o que cada valor significa.

Uma requisição também pode conter cabeçalhos, que são pares de nome e valor, e um corpo, que contém os dados enviados. Accept: application/json solicita uma resposta JSON. Content-Type: application/json descreve o corpo enviado. Authorization transporta credenciais. Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas, então content-type e Content-Type identificam o mesmo cabeçalho.

Escolher a ação

GET e HEAD são métodos seguros: sua finalidade é a leitura, então não use GET para um botão de exclusão. GET, PUT e DELETE são idempotentes. Repetir a mesma requisição deixa o servidor no mesmo estado pretendido que executá-la uma vez. Excluir uma nota já excluída pode retornar um status diferente, mas a nota continua ausente. Repetir um POST pode criar um segundo registro.

Interpretar a resposta

A resposta contém um código de status, cabeçalhos e geralmente um corpo. O primeiro dígito agrupa o resultado:

• 2xx: sucesso. 200 OK geralmente contém dados, 201 Created informa uma criação e 204 No Content não tem corpo.
• 3xx: redirecionamento. Por padrão, fetch segue redirecionamentos.
• 4xx: um problema com a requisição ou o acesso. 400 significa requisição inválida; 401 significa credenciais ausentes ou inválidas; 403 significa que o servidor entende a requisição, mas a recusa; 404 significa que o recurso não foi encontrado; 429 significa requisições em excesso.
• 5xx: um problema no servidor, como 500 Internal Server Error ou 503 Service Unavailable.

Uma chamada a /books/42 pode retornar 200, um tipo de conteúdo JSON e {"id":42,"title":"The Dispossessed","year":1974}. Uma chamada a /books/9999 pode retornar 404 e {"error":"Book not found"}. Ambas as chamadas receberam uma resposta. Uma falha de conexão não produz um status HTTP para o JavaScript inspecionar.

Inspecionar antes de supor

Abra as ferramentas de desenvolvimento, selecione Network e acione a operação. Inspecione o método, a URL completa, o status, os cabeçalhos, o corpo e os tempos. Compare-os com o ponto de acesso, os parâmetros obrigatórios, as credenciais, os limites de requisições por período e a resposta de exemplo da documentação. Se o servidor retornou os dados corretos, investigue o código da página; se a URL da requisição estiver errada, corrija-a antes de alterar a função de renderização.

fetch(url) envia uma requisição GET e retorna uma promessa. Seu resultado é um objeto Response, disponível quando os cabeçalhos chegam. Ler o corpo é uma operação assíncrona separada. response.json() lê esse corpo e o analisa, transformando-o em dados JavaScript.

Aguardar, verificar, ler

async function loadBook(id) {
  const response = await fetch(`https://api.example.com/books/${id}`);
  if (!response.ok) {
    throw new Error(`HTTP error ${response.status}`);
  }
  return await response.json();
}

Para loadBook(42), o primeiro await obtém a resposta. A condição rejeita um resultado HTTP malsucedido. O segundo await obtém os dados analisados do livro, como { id: 42, title: "The Dispossessed", year: 1974 }. A própria função retorna uma promessa, então quem a chama também aguarda o resultado.

response.ok é verdadeiro para status de 200 a 299. Um erro HTTP como 404 ou 500 não rejeita a promessa de fetch: um servidor respondeu. Uma falha de rede, uma troca bloqueada por CORS, uma URL de requisição inválida ou um cancelamento podem rejeitá-la. Lançar um erro para !response.ok permite que um try/catch envolvente também trate falhas HTTP.

Entender o corpo

Sem await, const data = response.json() armazena uma promessa, não o livro. Acessar data.title então resulta em undefined. Omitir await de fetch também deixa uma promessa onde o código espera um Response.

Escolha o leitor de corpo adequado para a resposta: json() para JSON, text() para texto ou blob() para dados binários. Um corpo só pode ser consumido uma vez. Armazene o resultado analisado e reutilize-o. Para inspecionar também o texto JSON bruto, leia text() uma vez e chame JSON.parse(text) nessa cadeia armazenada.

Um JSON inválido causa uma rejeição com SyntaxError. Uma página de erro em HTML frequentemente causa uma mensagem “Unexpected token '<'”. Um corpo vazio, incluindo uma resposta 204, também não pode ser analisado como JSON. Verifique primeiro o status e inspecione response.headers.get("Content-Type") quando houver dúvida sobre o formato. Um status de sucesso, por si só, não garante um corpo JSON.

Construir uma consulta com segurança

const url = new URL("https://api.example.com/search");
url.searchParams.set("q", "rock & roll");
url.searchParams.set("limit", 10);

O endereço resultante é https://api.example.com/search?q=rock+%26+roll&limit=10. O e comercial no valor é codificado como parte dele. Concatenar a entrada a "?q=" pode fazer &, # ou + assumirem seus significados em URLs e alterar a busca. Uma URL relativa segue a resolução normal de endereços: a partir de https://notes.example.org/app/index.html, fetch("data/books.json") carrega /app/data/books.json nessa origem.

Acompanhar a estrutura retornada

Para {"results":[{"title":"Dune"}],"total":1}, o primeiro título é data.results[0].title. O objeto externo não é o vetor de resultados. Use a prévia da resposta para encontrar o vetor antes de percorrê-lo.

Uma função auxiliar compartilhada getJSON(url, options) pode executar a mesma verificação de status e leitura do corpo para várias chamadas. Em uma cadeia .then(), retorne response.json() da função de retorno da resposta para que a próxima receba os dados analisados. Adicione .catch() ao final para tratar etapas rejeitadas.

O segundo argumento de fetch configura uma requisição. Suas opções incluem method, headers, body, signal e credentials. Sem essas opções, a requisição é um GET sem corpo. Para enviar JSON, você precisa preparar tanto seu texto quanto seu tipo de conteúdo.

Enviar JSON

const response = await fetch("https://api.example.com/notes", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Shopping", text: "Rice, lentils" }),
});

JSON.stringify produz {"title":"Shopping","text":"Rice, lentils"}. O cabeçalho informa ao servidor como ler esse texto. Passar o objeto diretamente como corpo envia "[object Object]". Enviar a cadeia JSON sem o cabeçalho identifica-a como text/plain;charset=UTF-8, que muitos pontos de acesso JSON rejeitam com 400 ou 415 Unsupported Media Type.

Uma criação bem-sucedida frequentemente retorna 201 com o registro armazenado, como {"id":17,"title":"Shopping","text":"Rice, lentils"}. Use esse objeto retornado para atualizar a página: o novo id do servidor é necessário para edições e exclusão posteriores.

Substituir ou atualizar

Um corpo de PUT que omite um campo pode fazer com que esse campo seja removido ou redefinido, de acordo com a API. Use o método documentado para a alteração pretendida. PUT e PATCH podem retornar um registro atualizado com 200 ou retornar 204 sem corpo.

Trate o sucesso sem supor que sempre haverá JSON:

if (!response.ok) {
  throw new Error(`HTTP error ${response.status}`);
}
const saved = response.status === 204
  ? null
  : await response.json();

Esse padrão serve para pontos de acesso documentados para retornar JSON ou 204. Uma exclusão pode ser bem-sucedida e ainda produzir um erro de análise sintática se o código chamar json() no corpo vazio sem verificar.

Escolher o formato do corpo

new FormData(formElement) coleta campos nomeados de formulário e arquivos selecionados. Passe-o diretamente como body. Deixe o navegador definir Content-Type: multipart/form-data e seu delimitador; um cabeçalho fornecido manualmente pode omitir o delimitador necessário para separar os campos. Um corpo URLSearchParams usa application/x-www-form-urlencoded.

GET e HEAD não podem transportar um corpo por meio de fetch. Coloque termos de busca e filtros na cadeia de consulta da URL. Tentar um GET com corpo resulta em rejeição com um TypeError antes que ele possa servir como requisição de busca.

Finalizar com segurança após sucesso ou falha

Desabilite o botão de envio antes de aguardar uma requisição de criação e habilite-o novamente em finally. Caso contrário, um clique duplo pode enviar duas requisições POST e criar dois registros. Não repita automaticamente uma operação de criação cujo resultado seja incerto: uma resposta perdida não confirma se o servidor fez a alteração.

Para um status de erro, o corpo pode conter uma mensagem útil como {"error":"title is required"}. Leia-o uma vez se for JSON; capture uma falha de análise sintática e mantenha uma mensagem HTTP geral para respostas vazias ou em HTML. Mantenha disponível o texto digitado pelo usuário para que ele possa corrigir a requisição.

A renderização transforma um vetor ou objeto em elementos na página. Mantenha os dados obtidos em uma variável e passe-os para uma função de renderização. Essa separação permite ordenar ou filtrar os mesmos dados sem pedi-los novamente ao servidor.

Criar um elemento por item

function renderBooks(books, list) {
  list.replaceChildren();
  for (const book of books) {
    const item = document.createElement("li");
    item.textContent = `${book.title} (${book.year})`;
    list.append(item);
  }
}

Para [{"title":"Kindred","year":1979},{"title":"Beloved","year":1987}], isso cria dois itens de lista: “Kindred (1979)” e “Beloved (1987)”. Limpar o contêiner primeiro faz uma nova busca substituir a anterior. Sem essa etapa, as listas antiga e nova se acumulam.

Manter texto externo como texto

Use textContent para títulos, descrições e outros textos de APIs. innerHTML analisa uma cadeia como marcação. Um título que contém <img src="x" onerror="alert(1)"> pode então executar código. Isso é injeção de scripts entre sites, ou XSS. Textos de formulários e do armazenamento precisam do mesmo tratamento, pois também podem ter vindo de uma fonte não confiável.

Propriedades de elementos definem valores individuais, como img.alt = book.title. Elas não tornam automaticamente todos os tipos de valor seguros. Um link fornecido por uma API ainda precisa de uma verificação de protocolo:

try {
  const target = new URL(book.url, location.href);
  if (target.protocol === "https:" || target.protocol === "http:") {
    link.href = target.href;
  }
} catch {
  link.removeAttribute("href");
}

Esse código é executado em um link recém-criado sem um href existente. Uma URL inválida ou não permitida deixa-o sem destino. Uma URL javascript: não é uma navegação web comum. Para imagens, forneça um texto alt significativo construído a partir dos dados quando possível.

Fornecer valores padrão sem perder valores reais

Campos opcionais podem estar ausentes ou ser null. book.author?.name ?? "Unknown author" primeiro tenta obter o nome aninhado e depois fornece um valor padrão. O encadeamento opcional evita acessar uma propriedade de um autor ausente.

O operador importa: 0 || "n/a" fornece "n/a", enquanto 0 ?? "n/a" mantém 0. O operador || substitui todos os valores avaliados como falsos, incluindo zero e uma cadeia vazia; ?? substitui apenas null e undefined. Um livro com zero exemplares disponíveis precisa exibir zero.

Um vetor de resultados vazio é uma busca bem-sucedida sem correspondências. Mostre “Nenhum livro corresponde à sua busca.” para que os leitores possam distingui-la de uma página que não carregou.

Substituir uma busca, adicionar outra página

Muitas APIs retornam páginas usando page, limit, uma contagem total ou uma URL next. Com 47 resultados e 10 por página, quatro páginas completas contêm 40 registros e a quinta contém 7. Uma nova busca limpa a lista anterior; “Carregar mais” adiciona a próxima página à lista atual. Mantenha essas duas ações de exibição separadas.

Para ordenar uma cópia local com os mais recentes primeiro, use [...books].sort((a, b) => b.year - a.year) e renderize essa cópia. O espalhamento cria um novo vetor, então a ordem salva da resposta continua disponível. Inspecione a estrutura da resposta antes de selecionar o vetor: uma API paginada frequentemente o coloca dentro de data.results.

APIs retornam valores fáceis de trocar entre programas. Os leitores precisam de datas, horários e quantias formatados para seu idioma e sua região. Mantenha o valor armazenado separado do texto usado para exibi-lo.

Ler primeiro o formato da data

"2026-03-05T14:30:00Z" identifica um instante: 14:30 UTC de 5 de março de 2026. O Z significa UTC. new Date(...) transforma-o em um Date JavaScript. Uma cadeia apenas com data, como "2026-03-05", é interpretada como meia-noite UTC; uma data e hora sem deslocamento, como "2026-03-05T14:30", é interpretada como horário local.

Uma marca de tempo Unix conta a partir de 1 de janeiro de 1970, UTC. APIs frequentemente contam segundos, mas Date recebe milissegundos. new Date(1772721000 * 1000) fornece o mesmo instante de 5 de março. Omitir a multiplicação resulta em uma data em janeiro de 1970. Leia a documentação da API para identificar a unidade.

Escolher uma configuração regional e um fuso horário

const date = new Date("2026-03-05T14:30:00Z");
const dateFormat = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "UTC",
});
dateFormat.format(date);

A saída é “Mar 5, 2026, 2:30 PM”. Com en-GB, é “5 Mar 2026, 14:30”. Usar datas curtas produz “3/5/26” em en-US, “05/03/2026” em en-GB e “05.03.26” em de-DE.

A configuração regional controla a apresentação; o fuso horário controla a hora local. Sem um timeZone, o formatador usa o fuso do dispositivo. Esse instante corresponde a 9:30 da manhã em Nova York, 15:30 em Amsterdã e 11:30 da noite em Tóquio. Mantenha e envie instantes em UTC e converta-os para exibição. Uma data de calendário, como um aniversário, exige cuidado: formatar meia-noite UTC em um fuso a oeste de UTC pode mostrar o dia anterior.

Manter a moeda separada da configuração regional

const priceFormat = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "EUR",
});
priceFormat.format(1234.5);

Isso fornece €1,234.50. Para a mesma quantia, de-DE com EUR fornece 1.234,50 €; en-US com USD fornece $1,234.50; en-US com JPY fornece ¥1,235. JPY não tem subunidade monetária, então sua exibição normal não tem casas decimais. Selecionar uma configuração regional não converte moedas. Use o código de moeda fornecido com a quantia.

Algumas APIs de pagamento enviam subunidades monetárias inteiras. Com USD, 1999 centavos significam 19.99 dólares: divida por 100 antes de formatar. Não aplique esse divisor a JPY. Somar centavos inteiros resulta em 1999 + 2550 = 4549, que é formatado como $45.49. Isso evita o conhecido resultado da aritmética decimal 0.1 + 0.2, que é 0.30000000000000004.

Reutilizar o formatador

Crie um formatador uma vez para uma lista. Use undefined como sua configuração regional para selecionar o padrão do navegador; navigator.language informa a identificação do idioma preferido do navegador. Outras opções formatam 0.256 como “26%” ou 12.5 com a unidade "kilometer-per-hour" como “12.5 km/h”. new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(-1, "day") fornece “yesterday”. Datas montadas manualmente, como “03/05/2026”, continuam ambíguas entre regiões.

Uma requisição tem um ciclo de vida visível: inativa, carregando e, em seguida, sucesso ou erro. O sucesso pode conter dados ou um resultado vazio. A página deve explicar cada estado para que os leitores saibam se devem esperar, alterar uma busca ou tentar novamente.

Manter a preparação e a limpeza juntas

Nesse tratador, getJSON verifica o status HTTP e analisa o corpo, searchUrl constrói a URL da requisição e renderResults atualiza a lista. O botão e o elemento de status já existem na página.

async function search(query) {
  button.disabled = true;
  status.textContent = "Loading…";
  try {
    const data = await getJSON(searchUrl(query));
    renderResults(data.results);
    status.textContent = data.results.length === 0 ? "No results." : "";
  } catch (error) {
    status.textContent = "Could not load results. Check your connection and try again.";
    console.error(error);
  } finally {
    button.disabled = false;
  }
}

A preparação acontece antes da espera. O caminho de sucesso renderiza os resultados e trata um vetor vazio. O bloco catch substitui a mensagem de carregamento se qualquer etapa aguardada falhar. finally restaura o botão após qualquer um dos caminhos. Se a limpeza ocorresse apenas após um await bem-sucedido, uma falha deixaria o controle desabilitado.

Explicar a causa de forma útil

Um erro HTTP tem um status que orienta a mensagem. Para 404, diga que o item não foi encontrado. Para 401, peça ao usuário que entre na conta; para 403, explique que o acesso não é permitido. Para 429, peça que aguarde. Para 5xx, explique que o serviço está com um problema e sugira tentar mais tarde.

Um TypeError de fetch pode significar uma falha de rede, uma requisição bloqueada por CORS ou uma URL inválida. O JavaScript não recebe um diagnóstico detalhado e confiável de CORS; inspecione o console do navegador e a aba Network. Um SyntaxError de json() indica JSON inválido. Cancelamentos e limites de tempo produzem erros como AbortError e TimeoutError. Mantenha os detalhes técnicos no console e ofereça aos leitores uma ação que possam entender.

Tornar as mudanças perceptíveis

Use um elemento de status existente, como <p role="status"></p>. Suas alterações são anunciadas aos leitores de tela sem mover o foco. aria-live="polite" tem uma finalidade semelhante; role="alert" é adequado para erros urgentes. Um indicador de carregamento sozinho não comunica um resultado vazio ou uma requisição malsucedida.

Um botão Tentar novamente chama a função de carregamento outra vez. Repetir requisições 400 ou 404 sem alterações geralmente repete o problema. Falhas temporárias de rede ou do serviço podem justificar uma pequena sequência limitada de novas tentativas. A espera exponencial entre tentativas aumenta a pausa, por exemplo, 1 segundo, 2 segundos e depois 4 segundos. Respeite o cabeçalho de resposta Retry-After; ele pode informar uma espera em segundos ou uma data HTTP. Evite repetir automaticamente uma requisição de criação que talvez já tenha sido bem-sucedida.

Se uma atualização falhar, mas os dados anteriores ainda forem úteis, mantenha-os visíveis com uma nota como “Exibindo resultados das 10:42. Não foi possível atualizar.” Não faça resultados antigos parecerem atuais sem avisar.

Testar os caminhos difíceis

Use as ferramentas de desenvolvimento para tornar a conexão lenta, ficar offline e requisitar um caminho inexistente. Verifique se o carregamento aparece rapidamente, se uma requisição malsucedida o substitui, se um sucesso vazio tem sua própria mensagem e se os controles voltam a ficar utilizáveis.

Requisições podem continuar depois da ação que as iniciou. Uma resposta de busca pode chegar depois que o leitor digitou outra coisa, e um serviço lento pode deixar uma página esperando por tempo demais. Controle quais resultados ainda são relevantes, além de verificar se cada requisição foi bem-sucedida.

Cancelar o trabalho que não é mais necessário

Crie um AbortController, passe seu signal para fetch e chame abort() para cancelar a requisição. O cancelamento pode interromper tanto a espera pelos cabeçalhos quanto uma leitura do corpo em andamento. A rejeição normalmente se chama "AbortError".

const controller = new AbortController();
const response = await fetch(url, { signal: controller.signal });
// A cancel button can call controller.abort().
const data = await response.json();

Envolva os dois usos de await no tratamento de erros. Se seu código cancelar intencionalmente uma busca antiga, retorne silenciosamente para esse cancelamento esperado, em vez de dizer ao usuário que o serviço falhou.

fetch não tem uma opção timeout nativa. Use um sinal como AbortSignal.timeout(5000) para limitar a requisição a 5000 ms, ou 5 segundos de tempo ativo. Antes da chegada dos cabeçalhos, ela é rejeitada com TimeoutError; depois que os cabeçalhos chegam, o sinal pode interromper a leitura do corpo.

Impedir que buscas antigas prevaleçam

Uma condição de corrida ocorre quando a ordem de conclusão altera o resultado. Um leitor digita “ca” e depois “cat”. Se “ca” retornar por último e for renderizado, a tela deixará de corresponder à entrada.

Uma abordagem cancela a requisição anterior antes de cada nova requisição. Outra atribui um número a cada chamada e permite que apenas a mais recente atualize a página:

let latest = 0;
async function search(query) {
  const request = ++latest;
  try {
    const data = await getJSON(searchUrl(query));
    if (request !== latest) return;
    renderResults(data.results);
  } catch (error) {
    if (request !== latest) return;
    showError(error);
  }
}

A verificação também impede que uma falha antiga substitua um sucesso mais recente. Aplique a mesma verificação de relevância às mensagens de carregamento e à restauração dos controles quando as chamadas se sobrepuserem.

O adiamento até cessarem os eventos reduz a quantidade de chamadas iniciadas. Cancele o temporizador anterior a cada tecla pressionada e inicie outro, por exemplo, de 300 ms. Digitar “paris” rapidamente inicia então uma requisição após a pausa. Esse adiamento economiza requisições; por si só, ele não impede que uma resposta anterior ainda em andamento chegue atrasada.

Decidir o que pode ser executado em conjunto

Requisições independentes podem começar juntas:

const [user, posts] = await Promise.all([
  getJSON(userUrl),
  getJSON(postsUrl),
]);

Para durações de 300 ms e 500 ms, as duas levam cerca de 500 ms, em vez de cerca de 800 ms em sequência. Promise.all é rejeitado assim que uma entrada é rejeitada, mas não cancela as outras operações.

Use Promise.allSettled quando resultados parciais forem úteis. Ele aguarda todas as entradas e informa cada resultado como { status: "fulfilled", value } ou { status: "rejected", reason }. Um painel pode então mostrar seções bem-sucedidas ao lado de uma que falhou.

Requisições dependentes precisam permanecer em sequência. Se uma segunda URL precisar de um ID retornado pela primeira requisição, aguarde esse ID antes de construir a segunda requisição.

Uma origem combina o esquema, o host e a porta de uma URL. O caminho não faz parte dela. https://shop.example.com/cart e /help no mesmo site compartilham uma origem. Mudar para http://shop.example.com, https://api.example.com ou https://shop.example.com:8443 altera a origem. HTTPS normalmente usa a porta 443.

Quem permite a leitura da resposta?

A política de mesma origem limita quais recursos um script de página pode ler. Para uma busca em outra origem, o CORS permite que o servidor da API conceda acesso por meio de cabeçalhos de resposta. Uma página em https://notes.example.org que chama https://api.example.com/weather precisa da permissão da API para ler a resposta.

Access-Control-Allow-Origin: https://notes.example.org concede acesso a essa origem. O valor * permite qualquer origem para uma requisição sem credenciais. Se a resposta não tiver uma permissão correspondente, o navegador a oculta da página e fetch é rejeitada com um TypeError. O console fornece o diagnóstico de CORS; o JavaScript não recebe o motivo detalhado.

Adicionar Access-Control-Allow-Origin à requisição JavaScript não concede permissão. Ele é um cabeçalho de resposta controlado pelo servidor. Adicionar um cabeçalho personalizado à requisição pode gerar uma verificação prévia adicional.

Por que OPTIONS aparece antes de POST

Algumas requisições entre origens precisam de uma verificação prévia. O navegador envia primeiro OPTIONS, indicando o método pretendido em Access-Control-Request-Method e os nomes dos cabeçalhos que não constam da lista de segurança em Access-Control-Request-Headers. O servidor os permite com Access-Control-Allow-Methods e Access-Control-Allow-Headers, junto com a permissão para a origem.

Um GET, HEAD ou POST básico com apenas cabeçalhos permitidos pode evitar a verificação prévia. Os tipos de conteúdo permitidos incluem text/plain, application/x-www-form-urlencoded e multipart/form-data. Um POST com JSON, um cabeçalho Authorization, PUT ou DELETE exige verificação prévia, a menos que uma permissão anterior válida esteja em cache. Se a verificação prévia for recusada, a requisição real não será enviada.

Para uma requisição simples, a requisição real pode chegar ao servidor mesmo quando o navegador bloqueia posteriormente a leitura da resposta. Portanto, o CORS não substitui a autorização do servidor nem a verificação das entradas.

Cookies acrescentam outro requisito

O padrão credentials: "same-origin" envia cookies apenas para requisições da mesma origem. credentials: "include" também permite cookies elegíveis em requisições de outras origens. As regras SameSite dos cookies e as políticas para cookies de terceiros continuam em vigor.

Para permitir que o JavaScript leia uma resposta com credenciais, o servidor deve enviar Access-Control-Allow-Credentials: true e indicar explicitamente a origem da página. Access-Control-Allow-Origin: * não funciona com credenciais. Esses cabeçalhos não obrigam o navegador a enviar um cookie que seria bloqueado por outro motivo.

Diagnosticar sem ocultar o problema

mode: "no-cors" fornece uma resposta opaca com status 0 e sem corpo ou cabeçalhos legíveis. Ela não pode fornecer JSON a uma página. Uma requisição que funciona em curl também não comprova a permissão de CORS no navegador: clientes de terminal não aplicam essa política do navegador.

Inspecione o console e a aba Network. Verifique se a verificação prévia falhou ou se faltou permissão na resposta final. Corrija a configuração de resposta da API ou encaminhe a chamada pelo seu próprio servidor. Durante o desenvolvimento, sirva páginas de um servidor local: páginas file:// costumam ter origens opacas. Um servidor local ainda precisa de permissão de CORS ao chamar outra origem.

Uma chave de API identifica uma aplicação que faz chamadas para fins de uso, limites e cobrança. Um token de acesso concede acesso para um usuário ou uma sessão. Quem possui uma credencial utilizável pode agir com a autoridade dela, então decida onde ela deve ficar antes de adicioná-la a uma requisição.

Cabeçalhos protegem a localização, não o segredo do usuário

Provedores podem exigir Authorization: Bearer <token>, X-API-Key: <key> ou um parâmetro de consulta como api_key. Siga a documentação da API. Um cabeçalho evita colocar a credencial em uma URL completa que pode entrar em registros e ferramentas de análise. Um cabeçalho Authorization ou personalizado em uma chamada de outra origem normalmente provoca uma verificação prévia.

Um cabeçalho continua visível nas ferramentas de desenvolvimento. Visitantes podem inspecionar o JavaScript que baixam e as requisições que ele envia. Minificar o código ou ocultar um valor atrás de uma variável não o torna secreto.

Acompanhar a chave em uma requisição de previsão do tempo

Suponha que o código do navegador chame https://api.weather.example/v1/current?city=Lima&key=sk_live_4f9a2c. Qualquer pessoa que abrir a aba Network pode copiar a chave e usar a cota da conta. Mover esse valor para uma variável de ambiente usada na geração da versão de distribuição não ajuda se a geração inseri-lo no JavaScript entregue à página.

Um segredo mantido no servidor muda o caminho:

1. A página chama seu próprio site em /api/weather?city=Lima.
2. O servidor desse site adiciona o segredo e entra em contato com o provedor de previsão do tempo.
3. O servidor retorna os dados de previsão do tempo à página, mantendo o segredo fora da resposta.

O servidor ainda precisa controlar o acesso e o uso de seu ponto de acesso. Manter o segredo do provedor em um servidor não torna inofensivo o uso público ilimitado.

Alguns provedores emitem chaves para navegador destinadas a ser públicas. Aplique as restrições de domínio do provedor, limite as APIs permitidas e defina cotas de uso. Use uma chave dessa maneira apenas quando seu projeto documentado permitir; uma chave secreta de servidor não se torna uma chave para navegador ao receber uma restrição de domínio.

Responder à exposição

Mantenha arquivos de credenciais fora do controle de versão, por exemplo, listando .env em .gitignore. Isso impede que o arquivo seja incluído em um commit; não impede que a geração do front-end publique um valor incorporado ao código. Se uma chave for exposta, revogue-a e emita uma substituta. Removê-la do commit mais recente deixa o histórico anterior e quaisquer cópias intactos.

Proteger a troca e reduzir o desperdício

Use HTTPS para chamadas de API para que dados e credenciais sejam criptografados em trânsito. Uma chamada fetch de uma página HTTPS para uma API HTTP é bloqueada como conteúdo misto. A criptografia não impede que a pessoa que usa o navegador veja sua própria requisição.

Um limite de requisições por período restringe o uso, por exemplo, a 60 requisições por minuto. Chamadas acima do limite podem retornar 429 Too Many Requests. Armazene resultados adequados em cache, adie a busca até cessar a digitação e evite chamadas duplicadas. Se o servidor fornecer Retry-After, respeite a espera indicada em vez de repetir tentativas imediatamente.

A validação no cliente torna formulários mais fáceis de usar, mas qualquer pessoa pode chamar um ponto de acesso sem seu formulário. O próprio servidor deve validar requisições e autorizar ações. Ao exibir sua resposta, continue tratando cadeias de caracteres como texto não confiável e insira-as com textContent.

O armazenamento web oferece dois armazenamentos de pares chave-valor: localStorage e sessionStorage. Eles usam os mesmos métodos, então a principal escolha é por quanto tempo os dados devem durar e quais abas devem compartilhá-los.

Escolher o tempo de vida

Fechar a aba encerra seu armazenamento de sessão. Uma página recém-aberta que tenha uma página de origem pode começar com uma cópia do armazenamento de sessão dessa página, mas alterações posteriores permanecem separadas. Evite usar o armazenamento de sessão como forma de manter informações secretas de scripts.

O armazenamento segue as origens. https://app.example.com não pode compartilhar seu armazenamento com http://app.example.com. Caminhos na mesma origem o compartilham, então um prefixo como "notes-app:settings" ajuda a manter distintas as chaves de várias aplicações.

Usar os métodos de armazenamento

localStorage.setItem("notes-app:theme", "dark");
const theme = localStorage.getItem("notes-app:theme");
localStorage.removeItem("notes-app:theme");

setItem cria ou sobrescreve uma entrada. getItem retorna seu valor como cadeia de caracteres ou null se ela estiver ausente. removeItem remove uma entrada. clear() remove todas as entradas dessa área de armazenamento para a origem, o que pode afetar outros recursos no mesmo site. length e key(index) permitem inspecionar as chaves.

Use esses métodos em vez de atribuições de propriedades como localStorage.theme = "dark". Chaves como "length" ou "key" podem entrar em conflito com membros nativos quando acessadas como propriedades.

Converter valores deliberadamente

Após localStorage.setItem("count", 5), a leitura fornece "5". Adicionar 1 diretamente cria "51". Number(localStorage.getItem("count")) + 1 produz 6.

Um booleano armazenado apresenta uma armadilha semelhante. setItem("darkMode", false) armazena "false", e uma cadeia não vazia é avaliada como verdadeira. Leia com localStorage.getItem("darkMode") === "true" quando essas forem as duas cadeias esperadas no armazenamento.

Objetos e vetores precisam de JSON:

localStorage.setItem("settings", JSON.stringify({
  theme: "dark",
  fontSize: 18,
}));
const settings = JSON.parse(localStorage.getItem("settings"))
  ?? { theme: "light", fontSize: 16 };

Sem serialização, um objeto comum torna-se "[object Object]". JSON.parse(null) fornece null, então o valor padrão cobre uma entrada ausente. Uma cadeia armazenada malformada ainda precisa de try/catch, e os dados analisados precisam de uma verificação de estrutura antes do uso.

Manter o volume de trabalho pequeno

Chamadas ao armazenamento web são síncronas: o JavaScript aguarda cada uma na thread principal. Use-o para configurações, um rascunho ou uma lista curta, não para grandes coleções ou arquivos. IndexedDB fornece armazenamento assíncrono para volumes maiores de dados estruturados.

Navegadores atuais geralmente permitem cerca de 5 MiB em cada área de armazenamento web por origem. Um armazenamento cheio pode fazer setItem lançar QuotaExceededError; o acesso também pode falhar devido às configurações de privacidade do navegador. Trate a falha sem impedir o restante da aplicação de funcionar. As ferramentas de desenvolvimento mostram os armazenamentos na aba Application do Chrome e do Edge ou na aba Storage do Firefox, onde excluir entradas ajuda a testar primeiras visitas.

Uma aplicação geralmente carrega ao iniciar e salva ao alterar. Leia uma lista salva quando a página abrir, renderize-a e salve a lista atualizada após uma edição. O armazenamento do navegador é uma cópia de conveniência: ele pode estar ausente, danificado, desatualizado ou ter sido limpo.

Validar antes de restaurar

Esta função de carregamento espera um vetor salvo de cadeias de caracteres:

function loadTodos() {
  try {
    const value = JSON.parse(localStorage.getItem("todos"));
    if (Array.isArray(value) && value.every(item => typeof item === "string")) {
      return value;
    }
  } catch {
    // Continue with an empty list if reading or parsing fails.
  }
  return [];
}

JSON.parse sozinho não comprova que o valor é um vetor ou que seus itens são adequados para a aplicação. Um JSON válido como 42 ainda tem a estrutura errada. Um valor com versão, como { version: 2, todos: [...] }, permite que o código mais recente reconheça formatos antigos e os converta ou restaure um valor padrão.

Salve a lista em memória com localStorage.setItem("todos", JSON.stringify(todos)) após cada alteração. Capture também falhas de gravação; uma página deve poder continuar funcionando mesmo quando não consegue preservar o estado para o próximo recarregamento. Um rascunho de formulário que pertence apenas a uma visita pode usar sessionStorage.

Adicionar uma marca de tempo às respostas em cache

localStorage.setItem("weather", JSON.stringify({
  savedAt: Date.now(),
  data,
}));

Em um carregamento posterior, valide primeiro a estrutura e a marca de tempo do objeto em cache. Sua idade é Date.now() - savedAt. Use-o apenas enquanto essa idade for inferior a 10 * 60 * 1000, ou 600.000 ms. Um valor salvo às 10:00:00 tem 450.000 ms de idade às 10:07:30 e pode ser usado. Às 10:12:00, tem 720.000 ms, então busque um valor atualizado. Com exatamente 600.000 ms, ele está expirado segundo essa regra.

A expiração é uma lógica da aplicação: localStorage não exclui uma entrada quando seu intervalo de validade termina. Rejeite uma marca de tempo ausente ou inválida em vez de tratar uma idade desconhecida como atual. Você pode manter dados antigos visíveis durante uma atualização malsucedida se eles estiverem identificados como antigos.

Sincronizar outras abas

Quando uma aba altera localStorage, outras abas da mesma origem recebem um evento storage. A aba que grava não recebe seu próprio evento. O evento disponibiliza key, oldValue, newValue e url.

window.addEventListener("storage", (event) => {
  if (event.key === "theme") applyTheme(event.newValue);
});

Aplique o tema imediatamente também na aba que faz a gravação. Trate null quando uma chave for removida. Um evento storage não substitui a atualização do estado da sua própria página.

Decidir o que deve ficar em outro lugar

Não coloque senhas, números de cartão de pagamento ou chaves de API secretas no armazenamento web. Scripts da origem podem lê-lo, incluindo código de terceiros e scripts injetados. Limpe dados pessoais relevantes ao sair da conta em dispositivos compartilhados. Mantenha trabalhos importantes em um servidor ou ofereça exportação, pois usuários podem limpar os dados do site e sessões privadas os descartam.

Cookies são diferentes: requisições correspondentes os enviam ao servidor, e cookies HttpOnly não podem ser lidos por scripts da página. Eles são pequenos, cerca de 4 KB cada. O armazenamento web permanece no navegador e pode ser lido por scripts. IndexedDB é adequado para volumes maiores de dados estruturados por meio de uma API assíncrona.

A Geolocalização é uma API do navegador: um recurso fornecido pelo navegador, separado da linguagem JavaScript. Como outros recursos do dispositivo, ela pode estar indisponível ou ter seu uso recusado. Uma página de previsão do tempo deve continuar funcionando quando um leitor optar por digitar uma cidade.

Verificar o recurso e o contexto

Detecte o próprio recurso com "geolocation" in navigator. Verificar o nome de um navegador é menos confiável: versões e configurações alteram o que está disponível. A Geolocalização precisa de um contexto seguro, normalmente HTTPS; http://localhost também atende ao requisito para desenvolvimento. window.isSecureContext informa se a página atual atende ao requisito. HTTP simples no endereço de rede de outro dispositivo não é o mesmo que localhost.

Explique por que a localização é útil e solicite-a quando o leitor clicar em “Usar minha localização”. O navegador gerencia a solicitação de permissão. Uma pessoa pode permitir ou bloquear o acesso, e uma recusa anterior pode fazer uma chamada posterior falhar sem outra solicitação. O usuário altera essa decisão nas configurações do site.

Ler o resultado da função de retorno

navigator.geolocation.getCurrentPosition(success, error, options) usa funções de retorno. Em caso de sucesso, position.coords contém latitude e longitude em graus decimais e accuracy em metros. A precisão é um raio estimado de incerteza, não uma precisão decimal adicional. Em caso de falha, o código 1 significa permissão negada, 2 significa posição indisponível e 3 significa limite de tempo excedido.

As opções controlam a tentativa:

• enableHighAccuracy: solicita maior precisão; padrão false.
• timeout: limite de espera em milissegundos; padrão Infinity.
• maximumAge: idade máxima de uma posição em cache aceitável; padrão 0.

Use um limite de tempo finito para que a página tenha uma forma de sair da espera. watchPosition observa atualizações ao longo do tempo e retorna um ID; passe esse ID para clearWatch quando o acompanhamento precisar parar.

Envolver funções de retorno ao usar await

function getPosition(options) {
  return new Promise((resolve, reject) => {
    navigator.geolocation.getCurrentPosition(resolve, reject, options);
  });
}

async function useLocation() {
  if (!("geolocation" in navigator)) {
    showCityInput();
    return;
  }
  try {
    const { coords } = await getPosition({ timeout: 10000 });
    const url = new URL("https://api.example.com/weather");
    url.searchParams.set("lat", coords.latitude.toFixed(2));
    url.searchParams.set("lon", coords.longitude.toFixed(2));
    await loadWeather(url);
  } catch {
    showCityInput();
  }
}

Aqui, showCityInput exibe o controle de entrada manual e loadWeather solicita e renderiza a previsão do tempo. Conecte useLocation ao botão de localização. O bloco catch cobre a falha de localização e a requisição de previsão do tempo; em ambos os casos, a entrada manual continua disponível.

Solicitar apenas a precisão útil

Uma posição com latitude 52.3676, longitude 4.9041 e precisão 35 tem um raio estimado de cerca de 35 m. Arredondar para 52.37 e 4.90 reduz a precisão enviada ao serviço de previsão do tempo. Um intervalo de latitude de 0,01° equivale a cerca de 1,1 km; a distância entre longitudes varia com a latitude. Essa precisão regional é adequada para uma previsão sem compartilhar as coordenadas mais detalhadas.

Onde a API de Permissões estiver disponível, navigator.permissions.query({ name: "geolocation" }) informa "granted", "denied" ou "prompt". Detecte e trate essa API também. Seu estado ajuda a adaptar a interface, mas não substitui o tratamento de erros da chamada de localização.

A API da área de transferência permite que uma página copie texto sem pedir ao leitor que o selecione primeiro. Assim como a Geolocalização, ela precisa de verificações de disponibilidade, uma ação apropriada do usuário, tratamento de erros e uma alternativa.

Copiar durante o clique

navigator.clipboard.writeText(text) retorna uma promessa. Aguarde-a antes de informar sucesso. Um contexto seguro é obrigatório, e uma operação negada pode ser rejeitada com NotAllowedError. Chame-a diretamente de um tratador de clique: Firefox e Safari exigem uma interação recente do usuário, enquanto os requisitos do Chromium também podem depender da permissão de gravação na área de transferência.

copyButton.addEventListener("click", async () => {
  try {
    if (!navigator.clipboard?.writeText) {
      throw new Error("Copy unavailable");
    }
    await navigator.clipboard.writeText(codeField.value);
    copyButton.textContent = "Copied!";
  } catch {
    codeField.focus();
    codeField.select();
    copyButton.textContent = "Copy selected text: Ctrl+C / Cmd+C";
  }
  setTimeout(() => {
    copyButton.textContent = "Copy";
  }, 2000);
});

codeField é um campo de texto ou textarea e copyButton é o botão da página. Se a cópia falhar, selecionar o texto oferece uma opção pelo teclado: Ctrl+C em muitos sistemas ou Cmd+C no macOS. O texto do botão volta a ser “Copy” após 2000 ms. Nunca mostre “Copied!” antes de a promessa ser cumprida.

A leitura usa navigator.clipboard.readText() e tem controles mais rigorosos porque uma área de transferência pode conter material privado de outras aplicações. Um navegador pode exigir permissão ou apresentar uma solicitação de colagem. A permissão para gravar não estabelece permissão para ler.

Tratar a conectividade como um indício

navigator.onLine e os eventos online e offline da janela ajudam a mostrar uma faixa de conexão. Eles não estabelecem se sua API está acessível. Um dispositivo pode ter conexão de rede enquanto o servidor da API está fora do ar ou inacessível.

window.addEventListener("offline", () => {
  status.textContent = "You are offline.";
});

Continue tratando erros em torno de fetch mesmo quando navigator.onLine for verdadeiro. Use uma região dinâmica apropriada para a mensagem de status.

Ler uma busca compartilhável

A API URL lê a cadeia de consulta da própria página, além de construir URLs de APIs. Em https://books.example.org/search?q=dune, new URL(location.href).searchParams.get("q") retorna "dune". Leia esse valor ao carregar para restaurar uma busca de um link compartilhado. Um parâmetro ausente retorna null, então decida o que a tela inicial deve mostrar nesse caso.

Usar um método de aprendizado

Para outra API do navegador, leia sua sintaxe, regras de contexto seguro e permissão, tabela de compatibilidade e status Baseline na MDN. Depois, detecte o recurso, chame-o a partir de uma ação do usuário quando necessário, trate sua promessa ou funções de retorno e ofereça uma alternativa quando ele estiver ausente ou a permissão for negada.

A API de Notificações exibe notificações do sistema após a permissão; a API de Compartilhamento Web abre um menu de compartilhamento do dispositivo onde há suporte; Canvas desenha gráficos; APIs de mídia controlam áudio e vídeo. Uma API de mapas de terceiros pode adicionar uma biblioteca e uma chave do provedor. Suas credenciais seguem as mesmas regras de chaves secretas de qualquer outro serviço. Testar um navegador em localhost não comprova que outro dispositivo ou navegador tenha o mesmo suporte e contexto.