Buenas prácticas de codificación de URL para APIs REST

Por qué es importante la codificación de URL en las APIs

Una codificación de URL adecuada es fundamental en el desarrollo de APIs REST. Las URL codificadas incorrectamente pueden provocar solicitudes fallidas, vulnerabilidades de seguridad, pérdida de datos y problemas de interoperabilidad entre distintos sistemas y lenguajes de programación. Como desarrollador de APIs, necesitas entender tanto cómo codificar las URL al realizar solicitudes como cómo decodificarlas al gestionarlas.

Codificación de parámetros de ruta

Las APIs REST suelen utilizar parámetros de ruta para identificar recursos. Cuando estos parámetros contienen caracteres especiales, una codificación adecuada es imprescindible:

// Parámetro de ruta con caracteres especiales
// 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)}`;

// Ruta con una barra diagonal en el valor
// Archivo: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Codificación de parámetros de consulta

Los parámetros de consulta son el lugar más habitual donde surgen problemas de codificación. Codifica siempre tanto las claves como los valores:

// Múltiples parámetros con caracteres especiales
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();

Manejo de arrays y objetos en las cadenas de consulta

Los distintos frameworks de API gestionan los parámetros de tipo array de forma diferente. Estas son las convenciones más comunes:

// Claves repetidas (lo más común)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Notación con corchetes (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Separados por comas (algunas APIs REST)
GET /api/items?tags=javascript,typescript,react

// Objetos anidados (notación con corchetes)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type y codificación

El encabezado Content-Type determina cómo se codifican los datos del cuerpo de la solicitud:

• application/x-www-form-urlencoded - Similar a las cadenas de consulta de una URL. Las claves y los valores se codifican y los espacios se convierten en +
• multipart/form-data - Se utiliza para la carga de archivos. Cada parte tiene su propia codificación
• application/json - Formato JSON. No se necesita codificación de URL para el cuerpo, pero el Content-Type debe estar configurado correctamente

Consideraciones de seguridad en las APIs

• Valida y sanea siempre los parámetros de URL decodificados en el servidor
• Ten en cuenta los ataques de path traversal mediante secuencias codificadas como %2e%2e%2f (../)
• Implementa límites de longitud de URL para evitar ataques de denegación de servicio
• Nunca confíes en la codificación del lado del cliente: vuelve a validar siempre en el servidor
• Presta atención a los ataques de doble codificación, en los que una entrada maliciosa elude los filtros tras una ronda de decodificación
• Usa consultas parametrizadas para prevenir la inyección de SQL incluso después de la decodificación de la URL

Pruebas de codificación de URL en las APIs

Al probar los endpoints de tu API, incluye casos de prueba para los siguientes escenarios:

• Parámetros con espacios (prueba tanto %20 como +)
• Parámetros con caracteres reservados (&, =, ?, #)
• Parámetros con caracteres Unicode
• Valores de parámetros vacíos
• Valores de parámetros muy largos
• Entradas ya codificadas (detección de doble codificación)
• Parámetros con bytes nulos (%00)