Guia Completa de URL Encoding

"Envie parametros en espanol a la API y volvieron corruptos."

Enviado: ?name=Juan Garcia
Recibido: ?name=Juan%20Garcia

La causa de este problema es URL encoding. Entenderlo correctamente significa que nunca mas lucharas con caracteres rotos.

---

Por Que es Necesario el Encoding

Las URLs se crearon en los 1990s y solo permiten caracteres ASCII.

Caracteres Seguros en URLs

A-Z  a-z  0-9  - _ . ~

Eso es todo.

Caracteres Problematicos en URLs

Que Hace el Encoding

Convierte caracteres problematicos al formato %XX (hexadecimal).

Espacio -> %20
&       -> %26
n       -> %6E (por ejemplo)

---

Funciones de Encoding en JavaScript

Diferencias Clave

const text = "hello world&name=Juan Garcia";

encodeURI(text);
// "hello%20world&name=Juan%20Garcia"
// & y = permanecen intactos (preserva estructura URL)

encodeURIComponent(text);
// "hello%20world%26name%3DJuan%20Garcia"
// & -> %26, = -> %3D (codifica todo)

Cuando Usar Cual

Errores Comunes

// Incorrecto: encodeURIComponent en URL completa
const url = "https://api.com/search?q=prueba";
encodeURIComponent(url);
// "https%3A%2F%2Fapi.com%2Fsearch%3Fq%3Dprueba"
// No usable como URL!

// Correcto: Solo codificar el valor
const query = "prueba";
const url = `https://api.com/search?q=${encodeURIComponent(query)}`;
// "https://api.com/search?q=prueba"

---

URLSearchParams - La Forma Moderna

Usa URLSearchParams en lugar de codificacion manual.

Uso Basico

const params = new URLSearchParams({
  name: "Juan Garcia",
  city: "Ciudad de Mexico",
  tags: "desarrollador,frontend"
});

params.toString();
// "name=Juan+Garcia&city=Ciudad+de+Mexico&tags=desarrollador%2Cfrontend"

El encoding sucede automaticamente. Sin espacio para errores.

Con Objeto URL

const url = new URL("https://api.com/search");
url.searchParams.set("q", "Juan Garcia");
url.searchParams.set("page", 1);

url.toString();
// "https://api.com/search?q=Juan+Garcia&page=1"

Parsing (Decodificacion)

const url = new URL("https://api.com/search?name=Juan%20Garcia");

url.searchParams.get("name");  // "Juan Garcia" <- decodificado automaticamente!

---

Resolucion de Problemas Practicos

Problema 1: Doble Encoding

// Codificar un valor ya codificado
const encoded = "%20";
encodeURIComponent(encoded);
// "%2520"
// % -> %25 causando corrupcion completa

Solucion: Verificar si ya esta codificado antes de codificar

function safeEncode(str) {
  try {
    // Si ya esta codificado, decodificar primero y re-codificar
    return encodeURIComponent(decodeURIComponent(str));
  } catch {
    // Fallo de decodificacion = aun no codificado
    return encodeURIComponent(str);
  }
}

Problema 2: Dos Caras del Espacio

%20  vs  +

Ambos representan espacio pero tienen origenes diferentes.

encodeURIComponent("hello world");  // "hello%20world"
new URLSearchParams({q: "hello world"}).toString();  // "q=hello+world"

Ambos son procesados correctamente por servidores. Pero elige un metodo para consistencia.

Problema 3: El Framework Ya Codifica

axios, fetch, React Router, etc. codifican automaticamente.

// axios - codificacion automatica
axios.get('/search', { params: { name: 'Juan Garcia' } });
// Peticion: /search?name=Juan%20Garcia

// Incorrecto: Codificacion manual causa doble codificacion
axios.get('/search', { params: { name: encodeURIComponent('Juan Garcia') } });
// Peticion: /search?name=Juan%2520Garcia (roto)

Regla: Si usas un framework, no codifiques manualmente.

---

Manejo del Lado del Servidor

Node.js / Express

// Auto-decodificado
app.get('/search', (req, res) => {
  const name = req.query.name;  // "Juan Garcia"
});

// Igual para parametros de ruta
app.get('/users/:name', (req, res) => {
  const name = req.params.name;  // "Juan Garcia"
});

Python / Flask

from flask import request

@app.route('/search')
def search():
    name = request.args.get('name')  # "Juan Garcia"

PHP

$name = $_GET['name'];  // "Juan Garcia"
// PHP tambien auto-decodifica

---

Casos Especiales

Base64 en URL

Base64 estandar contiene +, /, = que causan problemas en URLs.

// Base64 estandar
btoa("hello");  // "aGVsbG8="

// Base64 seguro para URL
function base64UrlEncode(str) {
  return btoa(str)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');  // remover padding
}

base64UrlEncode("hello");  // "aGVsbG8"

JWT usa este formato.

Precaucion con Fragmento (#)

https://example.com/page?name=Juan#section
                                   ^
                        No enviado al servidor desde aqui

Todo despues de # (fragmento) es procesado solo en el navegador y no se envia al servidor.

---

Consejos de Depuracion

Barra de Direccion del Navegador

Los navegadores muestran URLs decodificadas para legibilidad.

Mostrado: https://example.com/users/Juan Garcia
Real: https://example.com/users/Juan%20Garcia

Verifica la URL real de la peticion en la pestana Network de las Herramientas de Desarrollo.

Pruebas con curl

# URL codificada directamente
curl "https://api.com/search?name=Juan%20Garcia"

# Dejar que curl codifique
curl -G "https://api.com/search" --data-urlencode "name=Juan Garcia"

---

Resumen

Principio Fundamental: Siempre que sea posible, deja que URLSearchParams o tu framework lo manejen, y evita la codificacion manual.

---

Herramientas Relacionadas