Monitorización de API: cómo comprobar la respuesta JSON, no solo HTTP 200

En resumen: Una API JSON puede devolver HTTP 200 con un cuerpo {"status":"error","message":"DB unavailable"} - la monitorización que solo observa el código de estado anuncia "UP". Una monitorización real de API también comprueba el contenido de la respuesta, no solo la capa HTTP.

El problema: HTTP 200 != API funcionando

Las convenciones REST API dicen usar códigos de estado correctamente (200 OK, 4xx client error, 5xx server error). En la práctica:

• Algunas API devuelven siempre 200, el error está en el body JSON
• Una API gateway puede transformar 5xx en 200 con error JSON
• Los endpoints frontend BFF a menudo envuelven backends y devuelven 200 si la comunicación ocurrió, aunque el backend falló
• Los endpoints GraphQL devuelven siempre 200, los errors están en el campo errors[]

Desde la perspectiva del monitoring clásico (código HTTP) todo está OK. Desde la perspectiva del cliente real la API está rota.

Content matching: palabras clave

El añadido más simple a la monitorización HTTP es keyword match. Defines una cadena que debe estar en la respuesta - si falta, alerta.

Ejemplo para endpoint health check:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Configura keyword match a "status":"ok". Si la DB cae y el endpoint devuelve "status":"degraded", el monitoring lo coge.

Negative matching: qué debería faltar

A veces es más útil comprobar que una cierta cadena NO está en la respuesta:

• "error" - error en el body
• "maintenance" - modo maintenance inesperado
• "deprecated" - endpoint API se hizo deprecated
• fragmentos de error SQL: "SyntaxError", "undefined", "null pointer" - errores backend filtrándose

Aserciones avanzadas - roadmap

El match de texto plano tiene límites. Para un monitoreo API serio, son apropiadas las aserciones estructuradas sobre estructura JSON (expresiones JSONPath) y las transacciones sintéticas multi-paso (login -> endpoint protegido -> logout).

Las aserciones JSONPath y las transacciones sintéticas multi-paso están en la roadmap de ePulz.io pero actualmente no están implementadas. Si las necesita hoy, combine un monitor HTTP de ePulz.io con su propio script que envíe el resultado a través de un monitor heartbeat (en caso de fallo simplemente no envíe el heartbeat).

Autenticación en el monitoring

El endpoint monitorizado a menudo requiere auth. Opciones:

• Bearer token en cabecera Authorization - típicamente token de monitoring long-lived sin expiración (debe guardarse seguro)
• Clave API en parámetro query - visible en logs, no preferido
• Firma HMAC - timestamp + URL + hash de body firmado con shared secret. Lo más seguro.
• mTLS - cert cliente al lado del monitoring. Adecuado para APIs internas.

Aviso de seguridad: Para monitoring crea una cuenta / token dedicado con permisos mínimos (endpoint health read-only, no token admin). Rota el token regularmente. Si el servicio de monitoring se filtra, no se filtra todo el acceso a la API.

Response time SLO

El response time de API es igual de importante que el código HTTP. Un cliente con timeout 30 s no ve la diferencia entre "API devuelve 200 en 25 s" y "API hizo timeout". Desde UX ambos son malos.

Configura:

• Hard timeout - tras 10-15 s monitoring anuncia DOWN
• Soft threshold - response time entre 500-2000 ms = warning (degraded performance)
• Trending alerts - alerta si el 95º percentil de response time sube un 50% en las últimas 24 h

Monitoring por endpoint

Una API grande tiene decenas de endpoints. No monitorices solo /health - hasta él puede mentir. Identifica 3-5 endpoints críticos:

• Operaciones business más usadas (POST /api/orders, GET /api/dashboard)
• Endpoint read para cache hit (respuesta rápida)
• Endpoint write con roundtrip DB
• Endpoint de integración externa (llama a tercera parte - detecta caídas de dependencias)

Monitoriza cada uno por separado. En incidente ves exactamente qué parte de la API cayó.

Conclusión

La monitorización de API no puede reducirse al código de estado HTTP. Una monitorización de calidad combina estado + content match + response time + granularidad por endpoint + autenticación, para parecerse a un cliente real - no solo un cliente HTTP.

Monitorización de API con keyword match

Código de estado + keyword en contenido + response time + auth headers. Granularidad por endpoint.

Probar durante 7 días →