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.