Referencia de la HTTP REST API

TinyMQ expone una API HTTP agnóstica del lenguaje. Cualquier cliente capaz de realizar peticiones HTTP — curl, Python requests, PHP, Node.js, Rust — puede interactuar con el broker sin necesidad de librerías especiales.

URL base: http://localhost:7800 (o el valor de tu configuración PORT)

---

Resumen de Endpoints

Método	Endpoint	Descripción
POST	/publish/{topic}	Publicar un mensaje
GET	/consume/{topic}	Consumir / long-poll de mensajes
POST	/ack/{topic}/{id}	Confirmar (ACK) un mensaje
POST	/requeue	Re-encola un mensaje (incrementa retry count)
POST	/api/queues/redrive	Re-encola (redrive) mensajes de la DLQ
POST	/webhook/{topic}	Registrar un webhook de push
POST	/api/topics	Crear un topic manualmente
POST	/api/groups	Crear un Consumer Group
GET	/api/groups	Listar Consumer Groups de un topic
GET	/api/cluster/status	Obtener diagnósticos del cluster
POST	/api/drain	Marcar nodo como drenando (mantenimiento controlado)
GET	/api/stats	Obtener estadísticas del broker
GET	/metrics	Obtener métricas de Prometheus
GET	/healthz	Endpoint de healthcheck
GET	/dashboard	Dashboard web interactivo

Dashboard/JSON API (alternativa):

Método	Endpoint	Descripción
GET	/api/queues	Listar todas las queues
POST	/api/queues/publish	Publicar mediante cuerpo JSON
POST	/api/queues/consume	Consumir mediante cuerpo JSON
GET	/api/queues/peek	Ver el contenido de la queue sin consumirlo
DELETE	/api/queues/purge	Vaciar todos los mensajes de una queue
DELETE	/api/queues/delete	Eliminar la queue por completo
GET	/api/queues/webhooks	Listar los webhooks de una queue

---

POST /publish/{topic}

Publica un mensaje en un topic. El topic se crea automáticamente en la primera publicación.

Parámetros de consulta

Parámetro	Tipo	Descripción
ttl	duration	Time-To-Live. El mensaje se descarta si no se consume antes de que expire. Ejemplos: 30s, 5m, 1h
delay	duration	Retraso en la entrega. El mensaje queda oculto hasta que transcurra esta duración. Ejemplos: 10s, 1m
broadcast	bool	Si es true, entrega el mensaje a todos los consumidores en espera simultáneamente (efímero — no se persiste)
priority	string	Encola con prioridad: high, normal o low. (Por defecto: normal)
idempotency	string	Establece auto para usar el SHA256 del payload como clave de idempotencia

Headers

Header	Descripción
Idempotency-Key	Una cadena única (p. ej. uuid). Si se envía una clave duplicada en un período de 5 minutos, se acepta en silencio pero se descarta.
X-MQ-*	Cualquier header personalizado que comience por X-MQ- se almacena junto con el mensaje.

Cuerpo de la petición

Bytes en bruto (JSON, texto plano, binario). Tamaño máximo: 2 MB.

curl -X POST "http://localhost:7800/publish/orders.eu?ttl=10m&priority=high" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn-12345" \
  -d '{"user_id": 42, "item": "laptop"}'

---

GET /consume/{topic}

Consume uno o más mensajes de un topic. Soporta long-polling.

Parámetros de consulta

Parámetro	Tipo	Por defecto	Descripción
timeout	duration	0s	Mantiene la conexión abierta durante este tiempo si la queue está vacía (long-polling). P. ej., 5s, 10s
limit	int	1	Número de mensajes a extraer en una sola llamada
auto_ack	bool	false	Si es true, los mensajes se confirman (ACK) inmediatamente al ser entregados
group	string	(vacío)	Nombre del Consumer Group para Pub/Sub. P. ej. billing
peek	bool	false	Si es true, lee los mensajes sin consumirlos ni confirmarlos (ACK)
filter_key	string	(vacío)	Smart Routing: Solo devuelve mensajes con esta clave JSON exacta
filter_val	string	(vacío)	Smart Routing: Valor a coincidir con filter_key

# Consumir con long-poll de 10s, lote de 5, confirmación automática, como grupo "billing"
curl "http://localhost:7800/consume/orders.eu?timeout=10s&limit=5&auto_ack=true&group=billing"

Respuesta

Mensaje único (limit=1, por defecto):

{
  "id": "a1b2c3d4-7c89-4b1a-9f5e-123456789abc",
  "topic": "orders.eu",
  "payload": "eyJ1c2VyX2lkIjogNDIsICJpdGVtIjogImxhcHRvcCJ9",
  "payload_text": "{\"user_id\": 42, \"item\": \"laptop\"}",
  "timestamp": "2026-06-18T10:00:00Z",
  "retry_count": 0
}

Codificación del payload

payload se devuelve como bytes codificados en Base64. Si los bytes forman texto UTF-8 válido, payload_text también se rellena por comodidad.

---

POST /ack/{topic}/{id}

Confirma (ACK) un mensaje, eliminándolo de la RAM y escribiendo un registro ACK en el WAL. Obligatorio cuando auto_ack=false.

curl -X POST http://localhost:7800/ack/orders.eu/a1b2c3d4-7c89-4b1a-9f5e-123456789abc

---

POST /requeue

Re-encola un mensaje, incrementando su retry_count. Tras 3 intentos, el broker lo envía a {topic}.dlq. El cuerpo de la petición debe ser un objeto JSON completo del mensaje.

---

POST /api/queues/redrive?queue={topic}

Re-encola (redrive) todos los mensajes de la cola de dead-letters ({topic}.dlq) de vuelta a la cola principal {topic}. Los contadores de reintentos se reinician a 0 y los mensajes son eliminados de la DLQ.

curl -X POST http://localhost:7800/api/queues/redrive?queue=orders.eu

---

POST /webhook/{topic}

Registra una URL para recibir mensajes de un topic mediante HTTP POST (patrón push/webhook).

curl -X POST http://localhost:7800/webhook/orders.eu \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.my-service.com/hook", "secret": "my-hmac-secret"}'

Si se proporciona secret, los POST salientes incluirán un header X-TinyMQ-Signature con una firma HMAC-SHA256 del payload.

---

POST /api/topics

Pre-inicializa un topic. Útil para configurar Consumer Groups o definir reglas de retención (Retain).

curl -X POST http://localhost:7800/api/topics \
  -H "Content-Type: application/json" \
  -d '{"name": "analytics.events", "policy": "reject", "retain": "24h"}'

• policy: Política de desbordamiento (reject o drop-oldest) cuando se alcanza el límite máximo (100 k).
• retain: Aplica automáticamente este TTL a todos los mensajes publicados en este topic.

---

GET /metrics

Devuelve las métricas estándar de Prometheus para observabilidad.

curl http://localhost:7800/metrics

---

GET /healthz

Endpoint de healthcheck utilizado para sondas de Docker/Kubernetes.

• 200 OK — el broker está sano y listo para recibir tráfico.
• 503 Service Unavailable — devuelto durante una elección (aún no hay leader reconocido) o cuando el node está en modo drain. Las readiness probes de Kubernetes dejarán de enrutar tráfico automáticamente.

curl http://localhost:7800/healthz

Respuesta en modo standalone:

{ "status": "ok", "version": "3.1.0", "uptime_seconds": 3600 }

Respuesta en modo cluster:

{
  "status": "ok",
  "version": "3.1.0",
  "uptime_seconds": 3600,
  "cluster_role": "leader",
  "cluster_term": 3
}

cluster_role puede ser: "leader", "follower" o "candidate".

Respuesta durante una elección:

{ "status": "electing" }

---

POST /api/drain

Marca el node como drenando de forma inmediata. Todas las peticiones posteriores devolverán 503 Service Unavailable. Pensado para reinicios de mantenimiento controlados — los load balancers y las readiness probes de Kubernetes dejarán de enrutar tráfico automáticamente.

curl -X POST http://localhost:7800/api/drain

Respuesta:

{ "status": "draining", "in_flight_requests": 3 }

El drenado es permanente durante el tiempo de vida del proceso

No existe una API de "un-drain". Para recuperar el node, reinícia el proceso. Usa tmq cluster drain <node-url> desde el CLI para evitar apuntar accidentalmente al node equivocado.

---

POST /api/groups & GET /api/groups

Gestiona Consumer Groups de forma explícita. Los grupos permiten que múltiples servicios independientes consuman mensajes idénticos sin que unos interfieran con los otros.

Crear un grupo:

curl -X POST http://localhost:7800/api/groups \
  -H "Content-Type: application/json" \
  -d '{"topic": "orders.eu", "group": "billing"}'

Listar grupos:

curl http://localhost:7800/api/groups?topic=orders.eu

---

GET /api/cluster/status

Devuelve información de diagnóstico sobre la participación del node en el cluster de alta disponibilidad de TinyMQ, incluyendo su rol, el término actual, la dirección del líder y el estado de salud de los peers.

curl http://localhost:7800/api/cluster/status

---

Dashboard JSON APIs (/api/queues/*)

Estos endpoints aceptan cuerpos JSON en lugar de parámetros en la ruta URL. Son utilizados extensamente por el dashboard integrado.

• GET /api/queues: Devuelve una lista de todas las queues activas.
• POST /api/queues/publish: Cuerpo JSON con {"queue": "topic", "payload": "...", "ttl": "...", "delay": "...", "priority": "...", "broadcast": false}
• POST /api/queues/consume: Cuerpo JSON con {"queue": "topic"}
• GET /api/queues/peek?queue=orders.eu: Devuelve un array de hasta 10 mensajes sin eliminarlos.
• POST /api/queues/redrive?queue=orders.eu: Re-encola (redrives) mensajes de la DLQ a la cola principal.
• DELETE /api/queues/purge?queue=orders.eu: Vacía la queue.
• DELETE /api/queues/delete?queue=orders.eu: Elimina la queue y su archivo WAL.
• GET /api/queues/webhooks?queue=orders.eu: Devuelve una lista de URLs de webhook para la queue.

---

Referencia de errores

Estado HTTP	Significado	Causa típica
400 Bad Request	Petición malformada	Topic faltante, cuerpo vacío, duración no válida
403 Forbidden	Acceso denegado	Límite de TINYMQ_MAX_TOPICS alcanzado
404 Not Found	Recurso no encontrado	Queue vacía (al consumir), ID de mensaje desconocido
409 Conflict	Ya existe	Crear un topic que ya existe
413 Request Entity Too Large	Payload demasiado grande	El payload supera los 2 MB
429 Too Many Requests	Contrapresión	Límite de RAM de la queue (100 k mensajes) alcanzado