Boas Práticas de Codificação de URL para APIs REST

Por Que a Codificação de URL Importa para APIs

A codificação de URL correta é fundamental no desenvolvimento de APIs REST. URLs codificadas de forma incorreta podem levar a requisições quebradas, vulnerabilidades de segurança, perda de dados e problemas de interoperabilidade entre diferentes sistemas e linguagens de programação. Como desenvolvedor de APIs, você precisa entender tanto como codificar URLs ao fazer requisições quanto como decodificá-las ao tratar requisições.

Codificando Parâmetros de Caminho

APIs REST frequentemente usam parâmetros de caminho para identificar recursos. Quando esses parâmetros contêm caracteres especiais, a codificação correta é essencial:

// Parâmetro de caminho com caracteres especiais
// Recurso: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// Usando JavaScript
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// Caminho com barra no valor
// Arquivo: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Codificando Parâmetros de Consulta

Os parâmetros de consulta são o local mais comum onde surgem problemas de codificação. Sempre codifique tanto as chaves quanto os valores:

// Múltiplos parâmetros com caracteres especiais
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// Usando URLSearchParams (recomendado)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

Lidando com Arrays e Objetos em Query Strings

Diferentes frameworks de API tratam os parâmetros de array de maneiras distintas. Estas são as convenções mais comuns:

// Chaves repetidas (mais comum)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Notação de colchetes (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Separado por vírgulas (algumas APIs REST)
GET /api/items?tags=javascript,typescript,react

// Objetos aninhados (notação de colchetes)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type e Codificação

O cabeçalho Content-Type determina como os dados do corpo da requisição são codificados:

• application/x-www-form-urlencoded - Semelhante às query strings de URL. Chaves e valores são codificados, e os espaços se tornam +
• multipart/form-data - Usado para uploads de arquivos. Cada parte tem sua própria codificação
• application/json - Formato JSON. Não é necessária codificação de URL para o corpo, mas o Content-Type deve ser definido corretamente

Considerações de Segurança em APIs

• Sempre valide e sanitize os parâmetros de URL decodificados no servidor
• Fique atento a ataques de path traversal por meio de sequências codificadas como %2e%2e%2f (../)
• Implemente limites de comprimento de URL para prevenir ataques de negação de serviço
• Nunca confie na codificação feita no lado do cliente -- sempre revalide no servidor
• Cuidado com ataques de codificação dupla, em que uma entrada maliciosa contorna os filtros após uma rodada de decodificação
• Use consultas parametrizadas para prevenir injeção de SQL mesmo após a decodificação da URL

Testando a Codificação de URL em APIs

Ao testar os endpoints da sua API, inclua casos de teste para os seguintes cenários:

• Parâmetros com espaços (teste tanto %20 quanto +)
• Parâmetros com caracteres reservados (&, =, ?, #)
• Parâmetros com caracteres Unicode
• Valores de parâmetro vazios
• Valores de parâmetro muito longos
• Entradas já codificadas (detecção de codificação dupla)
• Parâmetros com bytes nulos (%00)