Saltar a contenido

Uso básico

Interfaz de línea de comandos

La interfaz de línea de comandos de httptap ofrece varias opciones para personalizar tus solicitudes HTTP y la salida.

Sintaxis

httptap [OPTIONS] URL

Opciones

Compatibilidad con curl: Los flags habituales de curl se aceptan como alias. Cambia curl por httptap y sigue usando opciones familiares como -X/--request, -L/--location, -m/--max-time, -k/--insecure, -x y --http1.1; -f/--fail, -4/--ipv4, -6/--ipv6 y --resolve usan los mismos nombres que en curl. Esto no es un clon completo de curl: limítate a los flags coincidentes que se enumeran aquí.

Opciones de solicitud

-X, --request, --method METHOD

Especifica el método HTTP que se usará. Métodos admitidos: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

Los valores del método no distinguen entre mayúsculas y minúsculas.

Alias compatibles con curl: -X, --request.

httptap --method POST https://httpbin.io/post

Comportamiento por defecto: - Sin --data: usa GET por defecto - Con --data pero sin --method: cambia automáticamente a POST (similar a curl) - Con --method explícito: respeta el método especificado

-d, --data DATA

Envía datos en el cuerpo de la solicitud. Puede ser una cadena en línea o una referencia a un archivo usando la sintaxis @filename.

Datos JSON en línea: 

httptap --data '{"name": "John", "email": "john@example.com"}' https://httpbin.io/post

Cargar desde un archivo: 

httptap --data @payload.json https://httpbin.io/post

Los datos en línea se envían con los bytes exactos del argumento, como en curl; en sistemas POSIX esto incluye argumentos que no son UTF-8 válido.

Detección automática: - El Content-Type se detecta automáticamente (JSON, XML, texto plano) - Primero se comprueba la extensión del archivo (.json, .xml, .txt) - Recurre a la validación JSON

Ejemplos con distintos métodos: 

# POST (detectado automáticamente cuando --data está presente)
httptap --data '{"key": "value"}' https://httpbin.io/post

# PUT
httptap --method PUT --data '{"status": "updated"}' https://httpbin.io/put

# PATCH
httptap --method PATCH --data '{"field": "modified"}' https://httpbin.io/patch

# GET explícito con cuerpo (poco común, genera una advertencia)
httptap --method GET --data 'query-data' https://httpbin.io/get

-H, --header

Añade cabeceras HTTP personalizadas a la solicitud. Puede usarse varias veces.

httptap -H "Accept: application/json" https://httpbin.io

httptap \
  -H "User-Agent: MyApp/1.0" \
  -H "Authorization: Bearer token123" \
  https://httpbin.io/bearer

Los nombres de cabecera deben ser tokens HTTP (letras, dígitos y !#$%&'*+-.^_`|~) y los valores solo pueden contener caracteres ASCII imprimibles, espacios y tabuladores. Una cabecera que incumpla estas reglas, como un nombre con un espacio, un valor con CR, LF u otro carácter de control, o un valor no ASCII (httpx envía los valores de las cabeceras como ASCII), se rechaza con el código de salida 64 antes de realizar ninguna solicitud. El error indica la cabecera, pero nunca muestra su valor.

-L, --location, --follow

Sigue las redirecciones HTTP y muestra la temporización de cada paso de la cadena (máximo 10 redirecciones).

Alias compatibles con curl: -L, --location.

httptap --follow https://httpbin.io/redirect/3

Por defecto, httptap no sigue las redirecciones y se detiene en la primera respuesta de redirección (código de estado 3xx).

Si la respuesta sigue siendo una redirección tras seguir 10 redirecciones, httptap se detiene, imprime una advertencia, marca ese paso con redirect_limit_reached: true en la exportación JSON y sale con el código 47.

Al seguir redirecciones, httptap aplica las mismas reglas que curl y los navegadores:

  • Las cabeceras Authorization, Cookie y Proxy-Authorization solo se envían al origen original (esquema, host y puerto). En cuanto una redirección apunta a otro origen, se descartan para el resto de la cadena; una actualización de http a https en el mismo host con los puertos por defecto (80 → 443) las conserva.
  • 303 See Other, y 301/302 tras un POST, cambian la siguiente solicitud a GET sin cuerpo. 307 y 308 conservan el método y el cuerpo.

Si el Location de una redirección no se puede solicitar (un puerto no válido o fuera de rango, falta el host, un esquema distinto de http/https, un literal IPv6 mal formado), se conserva el paso 3xx y la cadena termina con un paso fallido para ese destino con el error Invalid redirect target: …, y httptap sale con el código 75. Sin --follow, la respuesta 3xx se muestra tal como se recibió, sea cual sea su Location.

Las credenciales de una URL Location (https://user:password@host/) se enmascaran en la salida y en la exportación JSON (https://user:****@host/), pero se sigue la URL real.

-m, --max-time, --timeout SECONDS

Aborta la cadena de solicitudes si el tiempo total transcurrido supera el número de segundos especificado.

El límite es un plazo estricto para toda la cadena, redirecciones incluidas: la resolución DNS, la conexión, la espera de la respuesta y la lectura del cuerpo lo comparten, y un servidor que se detiene o sigue enviando bytes con cuentagotas se corta cuando vence. El paso falla entonces con Request timeout: total deadline exceeded y httptap sale con el código 75.

Alias compatibles con curl: -m, --max-time.

httptap --timeout 10 https://httpbin.io/delay/2

El tiempo de espera por defecto es de 20 segundos.

--no-http2 / --http1.1

Desactiva la negociación de HTTP/2 y fuerza conexiones HTTP/1.1.

httptap --no-http2 https://httpbin.io

Por defecto, HTTP/2 está activado si el servidor lo admite.

Alias compatible con curl: --http1.1.

-4, --ipv4 y -6, --ipv6

Restringe la resolución DNS y la conexión a IPv4 o IPv6. Las opciones son mutuamente excluyentes.

httptap -4 https://example.com
httptap --ipv6 https://example.com

No pueden usarse con proxies HTTP, HTTPS o SOCKS5H, porque esos proxies resuelven ellos mismos el nombre de host de destino.

--resolve HOST:PORT:ADDR

Conecta un nombre de host y un puerto a una dirección IPv4 o IPv6 concreta conservando la cabecera Host original y el SNI de TLS. Resulta útil para probar un backend antes de un cambio de DNS o para evitar un registro DNS round-robin. La opción puede repetirse para distintos pares de host y puerto.

httptap --resolve api.example.com:443:203.0.113.10 https://api.example.com/health
httptap --resolve api.example.com:443:[2001:db8::10] https://api.example.com/health

Los nombres de host internacionalizados coinciden en cualquiera de sus formas: una entrada para bücher.example también se aplica a https://xn--bcher-kva.example/, y viceversa. httptap resuelve estos nombres en su forma IDNA 2008 (xn--…), el mismo nombre que envía en la cabecera Host y en el SNI de TLS.

--resolve se aplica a las conexiones directas y a los proxies SOCKS5 con DNS local. Los proxies HTTP, HTTPS y SOCKS5H resuelven el destino de forma remota, por lo que combinarlos con --resolve se rechaza, igual que con -4/-6.

-k, --insecure, --ignore-ssl

Desactiva la verificación del certificado TLS. Útil para depurar hosts autofirmados o certificados caducados.

httptap --ignore-ssl https://self-signed.badssl.com

Warning

Usa esta opción solo en redes de confianza. Desactiva la validación de certificados y relaja las restricciones de la negociación TLS.

Alias compatibles con curl: -k, --insecure.

-x, --proxy URL

Enruta las solicitudes a través del proxy especificado. Admite los protocolos HTTP, HTTPS, SOCKS5 y SOCKS5H.

Alias compatible con curl: -x.

# proxy HTTP
httptap --proxy http://proxy.local:8080 https://httpbin.io/get

# proxy SOCKS5 (DNS resuelto por el proxy)
httptap --proxy socks5h://proxy.local:1080 https://httpbin.io/get

# proxy SOCKS5 (DNS resuelto localmente)
httptap --proxy socks5://proxy.local:1080 https://httpbin.io/get

# Ignora las variables de entorno de proxy y conecta directamente
httptap --proxy "" https://httpbin.io/get

El flag --proxy tiene prioridad sobre las variables de entorno (HTTP_PROXY, HTTPS_PROXY, NO_PROXY). Usa --proxy "" para ignorar todas las variables de entorno de proxy y conectar directamente. Consulta Funciones avanzadas para más detalles sobre los protocolos de proxy, la resolución DNS y la configuración mediante variables de entorno.

Las credenciales de la URL del proxy (http://user:password@proxy:3128), incluidas las que proceden de variables de entorno, se usan para la conexión pero se enmascaran en la salida y en la exportación JSON (http://user:****@proxy:3128).

Un proxy indicado sin esquema (proxy.local:3128) se trata como http://, igual que en curl. Una URL de proxy mal formada (un esquema no admitido, falta el host, un puerto no válido o fuera de rango, un literal IPv6 sin cerrar) se rechaza con el código de salida 64 antes de realizar ninguna solicitud; el error muestra la URL con la contraseña enmascarada.

--cacert, --ca-bundle PATH

Usa un paquete de certificados CA personalizado (formato PEM) para la verificación TLS. Útil para endpoints internos firmados por una CA privada.

httptap --cacert ~/certs/company-ca.pem https://internal-api.example.com/health

Mutuamente excluyente con --ignore-ssl.

Opciones de salida

--compact

Muestra los resultados en un formato compacto de una sola línea, adecuado para el registro (logging).

httptap --compact https://httpbin.io/get

Salida:

Step 1: 200 GET https://httpbin.io/get | dns=8.9ms connect=97.0ms tls=194.6ms ttfb=446.0ms total=447.3ms | 389 B

--compact imprime una línea legible por humanos por cada paso (adecuada para registros y para el rastreo de cadenas de redirecciones) sin dejar de renderizar la cabecera de análisis y la tabla Redirect Chain Summary. El tamaño de la respuesta se muestra con la unidad apropiada (B, KB, MB). Para una salida procesable por máquinas, consulta --metrics-only.

--metrics-only

Genera métricas en bruto sin formato, ideal para scripting y automatización.

httptap --metrics-only https://httpbin.io

Salida:

Step 1: dns=30.1 connect=97.3 tls=199.0 ttfb=472.2 total=476.0 status=200 bytes=389 ip=44.211.11.205 family=IPv4 tls_version=TLSv1.2 proxy=direct

--json PATH

Exporta todos los datos de la solicitud a un archivo JSON. Usa - para escribir el JSON en stdout en su lugar; en ese caso se suprime el informe habitual para que la salida pueda canalizarse.

httptap --json report.json https://httpbin.io
httptap --json - https://httpbin.io | jq '.summary'

Si no se puede escribir el archivo, httptap sale con el código 73.

El archivo JSON contiene:

  • Desglose de tiempos de todas las fases
  • Información de red (dirección IP, detalles de TLS, información del certificado)
  • Metadatos de la respuesta (estado, cabeceras, tamaño del cuerpo)
  • Cadena completa de redirecciones (al usar --follow)
  • Evaluación de SLO (cuando se proporciona --slo)

--har PATH

Exporta la cadena de solicitudes como un archivo HTTP Archive (HAR 1.2) que pueden abrir las DevTools de los navegadores y los visores de HAR. Usa - para escribirlo en stdout; en ese caso se suprime el informe habitual. --har se puede combinar con --json, pero solo uno de ellos puede usar -.

httptap --follow --har run.har https://httpbin.io/redirect/2
httptap --har - https://httpbin.io/get | jq '.log.entries[].timings'

Si no se puede escribir el archivo, httptap sale con el código 73. Consulta Exportación HAR para ver la correspondencia de tiempos y los campos que añade httptap.

--prometheus PATH

Escribe los tiempos por fase en el formato del textfile collector de Prometheus. Las duraciones se exportan como gauges httptap_request_duration_seconds con las etiquetas host, step y phase, junto a httptap_request_success y httptap_last_run_timestamp_seconds; las rutas y las query strings nunca se usan como etiquetas.

httptap --prometheus /var/lib/node_exporter/httptap.prom https://httpbin.io/get

--otlp ENDPOINT

Exporta la ejecución como una única traza de OpenTelemetry: un span raíz, un span por cada paso de la solicitud y spans hijos para las fases de DNS, conexión, TLS, espera del servidor y transferencia. Instala primero la dependencia opcional:

pip install 'httptap[otel]'
httptap --otlp http://localhost:4318/v1/traces https://httpbin.io/get

--slo KEY=MS[,KEY=MS...], --slo-file PATH

Comprueba el paso final correcto frente a presupuestos de latencia por fase. Ante una violación, httptap sigue renderizando el informe completo pero sale con el código 4 para que el resultado pueda condicionar trabajos de CI, sondas de cron o comprobaciones de disponibilidad (readiness) de Kubernetes.

httptap --slo total=500,ttfb=200 https://httpbin.io/get

# Un umbral por línea; los valores en línea anulan los del archivo.
httptap --slo-file slo.txt --slo total=1000 https://httpbin.io/get

Claves admitidas: dns, connect, tls, ttfb, wait, xfer, total. Consulta la página dedicada Comprobación de umbrales SLO para la especificación completa, la precedencia de códigos de salida y recetas de CI/cron.

-f, --fail

Sale con el código 22 cuando cualquier solicitud completada devuelve HTTP 4xx o 5xx, sin dejar de renderizar el informe de tiempos completo ni de escribir la salida de --json. Los fallos de red y TLS conservan sus códigos de salida existentes, de mayor prioridad.

httptap --fail https://httpbin.io/status/500

--version

Muestra la versión de httptap y sale.

httptap --version

Métodos HTTP

httptap admite todos los métodos HTTP estándar:

  • GET - Recupera un recurso (por defecto cuando no se proporciona --data)
  • POST - Crea/envía un recurso (seleccionado automáticamente cuando se proporciona --data)
  • PUT - Reemplaza un recurso
  • PATCH - Actualiza parcialmente un recurso
  • DELETE - Elimina un recurso
  • HEAD - Obtiene solo las cabeceras
  • OPTIONS - Consulta los métodos permitidos

Lógica de selección de método

  1. Método explícito: --method siempre tiene prioridad
  2. Auto-POST: Cuando --data está presente sin --method, usa POST por defecto
  3. GET por defecto: Sin --data ni --method, usa GET

Ejemplos por caso de uso

Pruebas de API: 

# Crear recurso
httptap --data '{"title": "New Post"}' https://httpbin.io/post

# Actualizar recurso
httptap --method PUT --data '{"title": "Updated"}' https://httpbin.io/put

# Actualización parcial
httptap --method PATCH --data '{"status": "published"}' https://httpbin.io/patch

# Eliminar recurso
httptap --method DELETE https://httpbin.io/delete

Comprobaciones de estado: 

# Comprobación rápida (solo cabeceras)
httptap --method HEAD https://httpbin.io/status/200

# Respuesta completa
httptap https://httpbin.io/status/200

Flujo de la solicitud

Cada solicitud de httptap sigue estas fases:

  1. Resolución DNS - Búsqueda del nombre de dominio
  2. Conexión TCP - Establecer la conexión TCP (a través de un proxy HTTP CONNECT: conectar con el proxy y abrir el túnel)
  3. Negociación TLS - Negociar la conexión segura (solo HTTPS)
  4. Espera del servidor - Tiempo entre el envío de la solicitud y el primer byte de la respuesta
  5. Transferencia del cuerpo - Descargar el cuerpo de la respuesta

Entender la salida

Modo Rich (por defecto)

La salida rich por defecto muestra una tabla de cascada con:

  • Nombre de la fase y duración
  • Barra de progreso visual
  • Detalles de red (IP, versión de TLS, información del certificado)
  • Metadatos de la respuesta (estado, tamaño, cabecera Server, destino de la redirección)

Desglose de tiempos

  • DNS (ms) - Tiempo para resolver el dominio a una dirección IP
  • Connect (ms) - Tiempo para establecer la conexión TCP; a través de un proxy HTTP CONNECT también incluye el viaje de ida y vuelta de CONNECT, de modo que el establecimiento del túnel no se cuenta como espera del servidor. Cuando el host tiene varias direcciones y las primeras fallan, el tiempo dedicado a ellas también se cuenta aquí y en Total (como time_connect de curl)
  • TLS (ms) - Tiempo de la negociación TLS (solo HTTPS)
  • TTFB (ms) - Tiempo hasta el primer byte (incluye el procesamiento del servidor)
  • Transfer (ms) - Tiempo para descargar el cuerpo de la respuesta
  • Total (ms) - Duración de la solicitud de extremo a extremo

Información de red

  • Dirección IP - Dirección IP resuelta y familia (IPv4/IPv6)
  • Versión de TLS - Versión del protocolo (TLS 1.2, TLS 1.3)
  • Conjunto de cifrado - Conjunto de cifrado negociado
  • CN del certificado - Common Name del certificado del servidor
  • Caducidad del certificado - Días hasta que caduca el certificado

Ejemplos

Comprobación de estado básica

httptap https://httpbin.io/status/200

Solicitud de API con autenticación

httptap \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Accept: application/json" \
  https://httpbin.io/bearer

Seguir la cadena de redirecciones

httptap --follow https://httpbin.io/redirect/3

Exportar para análisis

httptap --json analysis.json --follow https://httpbin.io/redirect/2

Registrar en un archivo

httptap --metrics-only https://httpbin.io/delay/1 >> api-latency.log

¿Qué sigue?