Back

Comandos básicos de curl que todo desarrollador web debería conocer

Comandos básicos de curl que todo desarrollador web debería conocer

¿Nuevo en curl? Comienza con nuestra guía para principiantes: Making HTTP Requests with curl

Cuando depuras APIs o pruebas endpoints, necesitas herramientas rápidas y confiables que no requieran configuraciones complejas. Aunque las herramientas GUI como Postman tienen su lugar, los comandos curl para desarrolladores web ofrecen velocidad y flexibilidad incomparables para pruebas desde la línea de comandos. Esta referencia cubre los comandos curl esenciales que usarás a diario, desde peticiones GET básicas hasta patrones de autenticación avanzados.

Puntos clave

  • Domina primero las peticiones GET y POST básicas: cubren el 80% de las necesidades de pruebas de API
  • Incluye siempre headers apropiados para Content-Type y Authorization
  • Usa el modo verbose (-v) cuando depures problemas de conexión
  • Establece timeouts para prevenir que los scripts se cuelguen en entornos de producción
  • Guarda las respuestas en archivos para análisis y comparación
  • Sigue redirecciones con -L para cadenas de peticiones completas
  • Combina curl con herramientas como jq para mejor manejo de JSON

Comandos curl esenciales para pruebas de API

1. Petición GET básica

El comando curl más simple obtiene datos de cualquier URL:

curl https://api.github.com/users/octocat

Esto devuelve la respuesta JSON sin procesar. Para mejor legibilidad, canaliza la salida a través de un formateador JSON:

# macOS/Linux
curl https://api.github.com/users/octocat | jq

# Windows (requiere instalación de jq)
curl https://api.github.com/users/octocat | jq

Cuándo usar: Pruebas rápidas de endpoints de API, verificar si los servicios responden, o obtener datos para scripts.

2. Petición POST con datos JSON

Las APIs modernas esperan payloads JSON. Aquí te mostramos cómo enviarlos correctamente:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}' \
  https://api.example.com/users

Para JSON complejo, guárdalo en un archivo y referéncialo:

curl -X POST \
  -H "Content-Type: application/json" \
  -d @user-data.json \
  https://api.example.com/users

Cuándo usar: Crear recursos, enviar formularios, o probar endpoints POST con datos estructurados.

3. Agregar headers personalizados

Las APIs a menudo requieren headers específicos para autenticación, negociación de contenido, o parámetros personalizados:

curl -H "Authorization: Bearer your-token-here" \
     -H "Accept: application/json" \
     -H "User-Agent: MyApp/1.0" \
     https://api.example.com/protected-resource

Cuándo usar: Autenticación de API, establecer user agents, especificar formatos de respuesta, o agregar headers personalizados de aplicación.

4. Seguir redirecciones

Por defecto, curl se detiene en las redirecciones. Usa -L para seguirlas automáticamente:

curl -L https://bit.ly/shortened-url

Limita los saltos de redirección para prevenir bucles infinitos:

curl -L --max-redirs 5 https://example.com

Cuándo usar: Probar URLs acortadas, seguir redirecciones de API, o verificar cadenas de redirección en tus aplicaciones.

5. Guardar respuesta en archivo

En lugar de saturar tu terminal, guarda las respuestas directamente en archivos:

# Guardar con nombre de archivo original
curl -O https://example.com/data.json

# Guardar con nombre personalizado
curl -o my-data.json https://api.example.com/export

# Guardar headers y body por separado
curl -D headers.txt -o response.json https://api.example.com/data

Cuándo usar: Descargar archivos, guardar respuestas de API para análisis, o archivar resultados de pruebas.

6. Autenticación básica

Muchas APIs aún usan autenticación básica. Manéjala de forma segura:

curl -u username:password https://api.example.com/secure-endpoint

Para mejor seguridad, deja que curl solicite la contraseña:

curl -u username https://api.example.com/secure-endpoint

Cuándo usar: Probar APIs internas, acceder a endpoints de desarrollo, o trabajar con sistemas de autenticación legacy.

7. Salida verbose para depuración

Cuando las peticiones fallan o se comportan de manera inesperada, el modo verbose muestra exactamente qué está pasando:

curl -v https://api.example.com/endpoint

Esto muestra:

  • Headers de petición enviados
  • Headers de respuesta recibidos
  • Detalles del handshake SSL/TLS
  • Información de conexión

Cuándo usar: Depurar peticiones fallidas, entender el comportamiento de la API, o solucionar problemas de SSL.

8. Establecer timeouts

Prevén peticiones colgadas estableciendo timeouts de conexión y totales:

# Timeout de conexión de 10 segundos, timeout total de 30 segundos
curl --connect-timeout 10 --max-time 30 https://slow-api.example.com

Cuándo usar: Probar endpoints lentos, prevenir que los scripts se cuelguen, o trabajar con redes poco confiables.

9. Envío de datos de formulario

Para envíos de formularios tradicionales o subida de archivos:

# Datos de formulario estándar
curl -X POST -d "username=john&password=secret" https://example.com/login

# Subida de archivo
curl -F "file=@document.pdf" -F "description=Important doc" https://example.com/upload

Cuándo usar: Probar endpoints de formularios, subir archivos, o trabajar con datos multipart.

10. Incluir headers de respuesta

Ver tanto headers como body en la salida:

# Incluir headers con la respuesta
curl -i https://api.example.com/endpoint

# Solo headers (útil para verificar códigos de estado)
curl -I https://api.example.com/endpoint

Cuándo usar: Verificar códigos de respuesta, depurar problemas de caché, o examinar headers de API.

Comandos curl avanzados para desarrolladores web

Trabajar con cookies

Mantén el estado de sesión entre peticiones:

# Guardar cookies en archivo
curl -c cookies.txt https://example.com/login

# Usar cookies guardadas
curl -b cookies.txt https://example.com/dashboard

Configuración de proxy

Enruta peticiones a través de proxies para pruebas o seguridad:

curl --proxy http://proxy.company.com:8080 https://api.example.com

Manejo de certificados SSL

Para entornos de desarrollo con certificados autofirmados:

# Omitir verificación de certificado (solo desarrollo)
curl -k https://localhost:8443/api

# Usar certificado CA personalizado
curl --cacert custom-ca.pem https://secure-api.example.com

Consejos de rendimiento y automatización

Operaciones en lote

Prueba múltiples endpoints de manera eficiente:

# Múltiples URLs en un comando
curl https://api1.example.com https://api2.example.com

# Desde un archivo
curl -K url-list.txt

Formateo de salida

Haz las respuestas más legibles:

# Pretty-print JSON con jq
curl -s https://api.example.com/data | jq '.'

# Extraer campos específicos
curl -s https://api.example.com/users | jq '.[] | .name'

Manejo de errores

Haz que curl falle silenciosamente en errores HTTP para scripting:

curl --fail --silent https://api.example.com/endpoint || echo "Request failed"

curl vs. otras herramientas: cuándo usar qué

Usa curl cuando:

  • Pruebas rápidas desde línea de comandos
  • Scripting y automatización
  • Integración en pipelines CI/CD
  • Uso mínimo de recursos del sistema

Usa Postman cuando:

  • Colecciones de peticiones complejas
  • Colaboración en equipo
  • Inspección visual de respuestas
  • Flujos de trabajo de pruebas avanzados

Usa HTTPie cuando:

  • Prefieras sintaxis más legible
  • Pruebas de API centradas en JSON
  • Mejor formateo por defecto

Preguntas frecuentes

Usa la opción limit-rate para limitar las peticiones, por ejemplo limitando a 200 kilobytes por segundo. También puedes agregar retrasos entre peticiones en scripts usando comandos sleep.

La bandera -d envía datos como form-encoded, que es el valor por defecto para peticiones POST. La bandera -F envía datos como multipart form data, que es requerido cuando subes archivos.

Sí. Para hacer esto, envía una petición POST con un payload JSON que incluya tu consulta GraphQL.

Usa el modo verbose para inspeccionar el handshake SSL, omite temporalmente la verificación de certificados si es necesario usando la bandera insecure, o especifica una autoridad certificadora personalizada con la opción cacert.

Para autenticación basada en tokens, pasa el header Authorization con tu token. Para autenticación básica, usa la opción username y password. Para mejorar la seguridad, almacena valores sensibles en variables de entorno y referéncialos en tus comandos.

Conclusión

Estos comandos curl forman la base de las pruebas de API desde línea de comandos. Comienza con peticiones GET y POST básicas, luego incorpora gradualmente headers, autenticación y características avanzadas conforme crezcan tus necesidades. La clave es desarrollar memoria muscular para los patrones más comunes: una vez que puedas probar endpoints rápidamente desde la terminal, te encontrarás usando curl constantemente durante el desarrollo y depuración.

Los comandos curl para desarrolladores web proporcionan la base para pruebas y depuración eficientes de API. Estos comandos funcionan en todas las plataformas y se integran perfectamente en flujos de trabajo de desarrollo, convirtiéndolos en herramientas esenciales para el toolkit de cualquier desarrollador web.

Listen to your bugs 🧘, with OpenReplay

See how users use your app and resolve issues fast.
Loved by thousands of developers