Dominando curl en Localhost: Guía Rápida de Debugging para Desarrolladores

Cuando estás desarrollando y necesitas saber exactamente qué está devolviendo tu servidor en tu máquina local, el navegador puede engañarte. El navegador guarda caché, sigue redirecciones automáticamente y ejecuta JavaScript. curl (Client URL) es la herramienta de terminal definitiva porque te da la "verdad del terreno": te muestra los bytes exactos que salen de tu puerto local, sin filtros.

Aquí tienes una guía práctica para usar curl contra tu entorno de desarrollo, ideal para diagnosticar APIs o problemas de renderizado del lado del servidor (SSR).

1. Lo más básico: Hacer un GET (Ver el HTML o JSON)

El comando por defecto de curl hace una petición GET estándar. Es el equivalente a escribir la URL en tu navegador y presionar Enter, pero mostrándote el código fuente crudo en la terminal.

# Ideal para revisar qué entrega tu servidor en la primera carga
curl http://localhost:4000

Tip de productividad: Si el servidor devuelve un JSON gigante en una sola línea (muy común en APIs locales), puedes formatearlo pasándolo por jq o Python para que sea legible:

curl http://localhost:8080/api/datos | python3 -m json.tool

2. Inspeccionar Cabeceras (Headers) y Códigos de Estado

Muchas veces el problema no está en el contenido (body), sino en cómo responde el servidor. ¿Dio un error 500? ¿Están bien configurados los CORS?

Ver solo las cabeceras (Método HEAD)

Usa -I (i mayúscula) para pedirle al servidor solo la metadata sin descargar todo el contenido. Excelente para probar si un endpoint está vivo.

curl -I http://localhost:4200

Salida esperada:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 1042

Ver cabeceras y contenido

Usa -i (i minúscula) para ver ambas cosas: los headers HTTP seguidos del cuerpo de la respuesta.

curl -i http://localhost:4000/api/status

3. Hacer peticiones POST (Enviar datos a tu API)

Si estás probando el backend localmente y no quieres abrir Postman o Insomnia, curl es rapidísimo.

Para enviar datos estructurados, necesitas tres cosas: especificar el método (-X POST), decirle al servidor el tipo de contenido (-H "Content-Type: application/json") y enviar los datos (-d).

curl -X POST http://localhost:8000/api/usuarios \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Usuario", "rol": "admin"}'

Nota: El parámetro -X especifica el verbo. Puedes cambiar POST por PUT, PATCH o DELETE según lo que necesite tu API.

4. Seguir Redirecciones

Por defecto, si tu servidor local hace una redirección (un código 301 o 302), curl se detendrá y te mostrará el aviso de redirección, pero no seguirá la nueva URL. Para obligarlo a seguir la cadena hasta el destino final, añade -L (Location).

curl -L http://localhost:3000/ruta-antigua

5. Simulando lentitud o ver el detalle paso a paso

Si la petición local está fallando antes de llegar a tu código (por un problema de red interno, puertos bloqueados, o caída del proceso del servidor), usa la bandera -v (verbose). Esto te mostrará el "apretón de manos" (handshake) completo entre curl y tu servidor.

curl -v http://localhost:4000

Verás líneas con > (lo que tú envías) y < (lo que el servidor local te responde).

Resumen de Banderas Clave

• -I: Trae solo los headers (Hace un request HEAD).
• -i: Trae headers + contenido.
• -v: Modo verbose, muestra todo el proceso de conexión.
• -X: Define el método HTTP (POST, PUT, DELETE).
• -H: Añade un header a tu petición (ej. Authorization: Bearer <token>).
• -d: Envía un payload/data en el cuerpo de la petición.
• -L: Sigue automáticamente las redirecciones.