curl para APIs: probar encabezados, JSON, tiempos y certificados desde terminal

Publicado el 2026-10-26 por frfrand

Comandos curl útiles para investigar errores web y HTTP

curl para APIs: probar encabezados, JSON, tiempos y certificados desde terminal

Cuando una API falla, el navegador suele mostrar sólo «Network Error». curl te permite hacer la misma solicitud y ver headers, cuerpo, certificado y tiempos sin depender del frontend. Es una navaja suiza para distinguir error de código y error de infraestructura.

La idea es resolver un problema de datos o despliegue que aparece en aplicaciones reales. Vamos a ver el concepto sin vueltas, un ejemplo de implementación y qué comprobar antes de llevarlo a producción.

Qué hace curl para APIs

curl es un cliente de protocolos que admite HTTP, HTTPS y muchas opciones de depuración. Los headers muestran metadatos, el status refleja la respuesta del servidor y el modo verbose da información de conexión. Secreto importante: no pegues tokens reales en comandos compartidos o tickets.

No alcanza con repetir una receta si no entendés quién lee los datos, desde qué proceso y con qué permisos. En una aplicación con reservas, facturas o usuarios, una condición de carrera o una política de acceso mal hecha puede ser más grave que una API lenta.

Un ejemplo concreto

curl -i https://api.ejemplo.com/health
curl -I https://api.ejemplo.com/
curl --fail-with-body -sS https://api.ejemplo.com/health
curl -sS -o /dev/null -w 'status=%{http_code} total=%{time_total}\n' https://api.ejemplo.com/health
# POST de prueba sin credenciales
curl -i -X POST -H 'Content-Type: application/json' -d '{"plazas":2}' https://api.ejemplo.com/demo

Los nombres, tablas y claves de este ejemplo son ilustrativos. Probalo primero en una base o entorno de ensayo y adaptá permisos, índices y versiones. Cuando haya operaciones de escritura, no ejecutes consultas de muestra sobre datos de clientes sin revisar qué modifican.

Paso a paso

Comprueba GET en una ruta de salud y anota el estado HTTP.
Usa -i para ver los encabezados de respuesta; -I solicita HEAD, que no siempre está soportado.
Mide los tiempos para distinguir la lentitud de conexión del procesamiento.
Prueba un POST solo contra un endpoint de prueba que no cree cargos ni pedidos.
Si falla TLS, investiga el certificado y el nombre en lugar de desactivar la validación con -k.

Al final no te quedes con «el SQL no dio error». Comprueba el efecto real desde la API y con pruebas de concurrencia o permisos según corresponda. En las bases de datos hay errores que solo aparecen cuando dos usuarios hacen algo al mismo tiempo.

Ejemplo de proyecto de trabajo

Una tienda envía datos JSON pero la API espera otro nombre de campo. Con curl recibes 422 o 400 y un cuerpo que explica la validación, sin perderte investigando el proxy.

Ese escenario ayuda a distinguir el rendimiento de la consistencia. Acelerar una consulta no sirve si permite crear dos reservas para una sola plaza, ni una base de datos enorme arregla que el backend permita consultar datos de otro cliente.

El error típico

curl -I envía HEAD y puede devolver un error diferente a GET; para verificar una API que solo ofrece GET, usa GET. No publiques comandos con tokens bearer reales.

También conviene tener un plan de recuperación. Antes de tocar el esquema, usuarios o políticas, guarda una copia verificable o una migración reversible y comprueba que la aplicación pueda seguir funcionando durante el cambio.

¿Cómo lo resolvería con ArduMaker?

Si tu backend está en ArduMaker, compará la respuesta de curl con los logs de FastAPI, Django y Nginx desde el VPS. Es un diagnóstico más preciso que reiniciar servidores.

ArduMaker te permite desplegar servicios desde Git y trabajar con bases y procesos dentro del VPS. El panel no reemplaza la lógica de tu aplicación: transacciones, permisos y validaciones deben quedar correctamente diseñados en el código y la base de datos.

Tres comprobaciones antes de publicar

Integridad: si una petición se repite o falla a mitad de camino, ¿los datos terminan en un estado válido?

Seguridad: ¿un usuario autenticado puede acceder sólo a su información, y la API utiliza una identidad de base con permisos mínimos?

Recuperación: ¿sabés restaurar los datos y revertir la versión de código compatible si una actualización sale mal?

Si podés responder a esas tres preguntas con pruebas, tu backend está bastante mejor preparado que cuando sólo miraste si el endpoint devolvía 200.

Recursos para profundizar

Para cerrar: elegí la solución más simple que permita mantener datos correctos, seguros y recuperables. El rendimiento viene después de medir.