URL API no Node.js: Guia Prático

Aplicações Node.js recebem e constroem URLs o tempo todo: endpoints, callbacks, links, arquivos, proxies e integrações externas. A URL API no Node.js implementa o padrão da Web e oferece uma forma estruturada de analisar componentes como protocolo, hostname, porta, caminho, query string e fragmento.

Tratar URLs com concatenação de strings cria erros de encoding, barras duplicadas e parâmetros inválidos. Em cenários de segurança, uma validação superficial pode permitir redirecionamento aberto, SSRF, credenciais embutidas ou acesso a protocolos não permitidos. O objeto URL normaliza o endereço, mas a aplicação ainda precisa aplicar regras de negócio.

Neste guia, você aprenderá a criar e modificar URLs, usar URLSearchParams, resolver endereços relativos, converter arquivos, validar hosts e proteger operações que acessam destinos externos.

Criando um objeto URL

const address = new URL(
  'https://api.example.com:8443/users?id=42#details'
);

console.log(address.protocol); // https:
console.log(address.hostname); // api.example.com
console.log(address.port);     // 8443
console.log(address.pathname); // /users
console.log(address.search);   // ?id=42
console.log(address.hash);     // #details

A documentação oficial do módulo URL apresenta as classes e utilitários. O comportamento segue o padrão WHATWG URL, também usado por navegadores.

Para revisar a criação de endpoints, consulte como criar uma API com Node.js e o que é JavaScript.

URL relativa exige uma base

const url = new URL('/users/42', 'https://api.example.com');
console.log(url.href);

Sem uma base, uma URL relativa gera erro. A base também permite resolver ../, ./ e barras de forma padronizada.

Construindo endpoints sem concatenar strings

function createUserUrl(baseUrl, userId) {
  const url = new URL('/users/', baseUrl);
  url.pathname += encodeURIComponent(userId);
  return url;
}

const userUrl = createUserUrl(
  'https://api.example.com',
  'user/123'
);

Codifique valores inseridos em segmentos. Não codifique o caminho inteiro com encodeURIComponent(), pois as barras estruturais também seriam transformadas.

URLSearchParams

const url = new URL('https://example.com/search');

url.searchParams.set('q', 'Node.js e URLs');
url.searchParams.set('page', '2');
url.searchParams.append('tag', 'javascript');
url.searchParams.append('tag', 'backend');

console.log(url.href);

Os valores são codificados automaticamente. set() substitui os valores anteriores daquela chave; append() adiciona outro.

Lendo parâmetros repetidos

const params = new URLSearchParams(
  'tag=node&tag=javascript&page=1'
);

console.log(params.get('tag'));
console.log(params.getAll('tag'));

get() retorna o primeiro valor. Use getAll() quando a API aceita listas.

Iterando parâmetros

for (const [key, value] of params) {
  console.log(key, value);
}

Não converta automaticamente para objeto se chaves repetidas são relevantes, pois uma conversão simples pode descartar valores.

Query string não define tipos

Todos os valores chegam como texto. Converta e valide:

function parsePage(searchParams) {
  const raw = searchParams.get('page') || '1';
  const page = Number(raw);

  if (!Number.isInteger(page) || page < 1 || page > 1000) {
    throw new Error('Página inválida');
  }

  return page;
}

O texto false não é um booleano. Adote funções explícitas ou schema de validação. Veja Zod no TypeScript.

Removendo e verificando parâmetros

params.has('page');
params.delete('page');
params.sort();

Ordenar pode ser útil para construir uma chave de cache ou assinatura, desde que o protocolo defina essa normalização. Não altere a ordem antes de validar uma assinatura que depende dos bytes originais.

Usando URL em um servidor HTTP

const http = require('node:http');

http.createServer((req, res) => {
  const url = new URL(req.url, `http://${req.headers.host}`);

  if (url.pathname === '/products') {
    const category = url.searchParams.get('category');
    res.end(JSON.stringify({ category }));
    return;
  }

  res.statusCode = 404;
  res.end();
}).listen(3000);

O cabeçalho Host vem do cliente e não deve ser usado para decisões de segurança sem validação. Em proxies, configure hosts permitidos e cabeçalhos confiáveis.

Origin

const url = new URL('https://example.com:8443/path');
console.log(url.origin);

A origin combina esquema, hostname e porta. Ela não inclui caminho, query ou fragmento. Para comparar origens permitidas, analise os dois valores com URL e use uma lista explícita.

Hostname e host

• hostname contém apenas o nome ou IP;
• host inclui porta quando presente;
• port retorna uma string;
• protocol inclui dois-pontos.

Comparar host com um nome sem porta pode produzir resultado inesperado.

Credenciais em URLs

const url = new URL(
  'https://user:password@example.com/private'
);

console.log(url.username);
console.log(url.password);

Evite credenciais na URL. Elas podem aparecer em logs, histórico, métricas e mensagens de erro. Use headers ou configuração protegida.

Removendo dados sensíveis antes de registrar

function sanitizeUrl(input) {
  const url = new URL(input);
  url.username = '';
  url.password = '';

  for (const key of ['token', 'api_key', 'signature']) {
    if (url.searchParams.has(key)) {
      url.searchParams.set(key, '[REDACTED]');
    }
  }

  return url.href;
}

Não registre o endereço original antes da sanitização.

Protocolos permitidos

function validateHttpUrl(input) {
  const url = new URL(input);

  if (!['http:', 'https:'].includes(url.protocol)) {
    throw new Error('Protocolo não permitido');
  }

  return url;
}

Essa verificação impede file:, data: e outros esquemas, mas não é suficiente para proteger uma função que faz requisições externas.

SSRF e resolução DNS

Uma URL fornecida pelo usuário pode apontar para localhost, metadados de nuvem ou IP privado. O domínio também pode resolver para um endereço interno. Para reduzir SSRF:

• use uma lista de hosts permitidos quando possível;
• resolva o hostname e valide todos os IPs;
• bloqueie faixas privadas, loopback e link-local;
• controle redirecionamentos;
• valide novamente o destino de cada redirecionamento;
• aplique timeout e limite de resposta.

O guia de DNS no Node.js explica resolução e mudanças de endereço. Consulte também segurança em aplicações web.

Redirecionamento aberto

Um parâmetro next não deve aceitar qualquer URL:

function safeRedirect(target) {
  const base = new URL('https://app.example.com');
  const destination = new URL(target, base);

  if (destination.origin !== base.origin) {
    throw new Error('Destino externo não permitido');
  }

  return destination.pathname + destination.search;
}

Retornar apenas caminho e query impede que credenciais ou fragmentos inesperados sejam propagados.

Normalização

const url = new URL('HTTPS://EXAMPLE.COM:443/a/../b');
console.log(url.href);

O objeto normaliza esquema, hostname, porta padrão e segmentos. Não confunda normalização com autorização. Duas representações equivalentes ainda precisam seguir as regras da aplicação.

URLs internacionais

Domínios com caracteres Unicode são convertidos para uma forma ASCII compatível. Para exibição ao usuário, mantenha cuidado com caracteres visualmente semelhantes e phishing.

urlToHttpOptions()

const { urlToHttpOptions } = require('node:url');
const https = require('node:https');

const url = new URL('https://example.com/path?q=node');
const request = https.request(urlToHttpOptions(url));

Muitas APIs HTTP já aceitam diretamente um objeto URL. Prefira essa forma quando disponível.

fileURLToPath()

ES Modules usam URLs para localizar o arquivo atual:

import { fileURLToPath } from 'node:url';
import path from 'node:path';

const filename = fileURLToPath(import.meta.url);
const dirname = path.dirname(filename);

Não use diretamente new URL(...).pathname como caminho, pois encoding e regras do Windows podem produzir erros. Veja ES Modules no Node.js.

pathToFileURL()

const { pathToFileURL } = require('node:url');

const fileUrl = pathToFileURL('/srv/app/config.json');
console.log(fileUrl.href);

Essa função trata separadores e encoding corretamente. Para operações no disco, consulte File System no Node.js.

URLPattern

Versões atuais do Node.js podem oferecer URLPattern conforme a versão e estabilidade. Ele permite comparar padrões de host e caminho. Confirme a versão mínima antes de adotar em biblioteca ou produção.

Construindo URLs para assinatura

APIs assinadas podem exigir ordem, encoding e inclusão exata de componentes. Não use uma normalização diferente da especificação. Construa uma função canônica testada com vetores oficiais e não modifique a query depois de assinar.

Para HMAC, veja Crypto no Node.js e webhooks seguros com Node.js.

Limites de tamanho

URLs e query strings enormes consomem CPU e memória em parsing, logs e validação. Servidores e proxies possuem limites próprios. Restrinja quantidade de parâmetros, tamanho total e tamanho de cada valor.

Testando URLs

Inclua casos com:

• URL absoluta e relativa;
• parâmetros repetidos;
• Unicode e espaços;
• porta padrão e personalizada;
• credenciais embutidas;
• protocolo não permitido;
• host em caixa alta;
• redirecionamento externo;
• IPv4 e IPv6;
• caminho de arquivo no Windows e Linux.

Erros comuns

• Concatenar query manualmente: encoding e separadores ficam incorretos.
• Confiar no cabeçalho Host: o cliente pode controlá-lo.
• Validar apenas o protocolo: SSRF continua possível.
• Registrar tokens na query: segredos vazam.
• Usar pathname de file URL como caminho: plataformas divergem.
• Descartar parâmetros repetidos: dados são perdidos.
• Comparar strings não normalizadas: URLs equivalentes parecem diferentes.
• Normalizar antes de validar assinatura: os bytes deixam de corresponder.

Boas práticas para produção

• Use URL e URLSearchParams.
• Converta e valide os tipos da query.
• Aplique allowlist de protocolos e hosts.
• Valide IPs e redirecionamentos em fetch externo.
• Remova credenciais e tokens dos logs.
• Use utilitários de file URL.
• Limite tamanho e quantidade de parâmetros.
• Não confunda normalização com autorização.
• Teste Unicode, IPv6 e portas.
• Siga a canonicalização definida pelo protocolo.

Conclusão

A URL API no Node.js oferece parsing e construção padronizados para endereços HTTP, arquivos e parâmetros. O objeto URL separa componentes e URLSearchParams cuida do encoding da query.

O parsing correto é apenas o primeiro passo. Hosts, protocolos, redirecionamentos e IPs precisam seguir uma política de segurança. Com validação, limites e logs sanitizados, URLs podem ser manipuladas sem depender de concatenação frágil ou verificações incompletas.