Monitoreo de API: cuando un HTTP 200 no basta

Una API JSON puede devolver un HTTP 200 con un cuerpo que describe un error - el monitoreo basado en el código de estado lo declarará UP. El monitoreo de API real comprueba también el contenido de la respuesta, no solo el HTTP.

El problema: HTTP 200 ≠ API funcional

Según las convenciones de las API REST, los códigos de estado deben usarse correctamente (200 OK, 4xx error del cliente, 5xx error del servidor). En la práctica:

Algunas API siempre devuelven 200 y el error está en el cuerpo JSON
Un API gateway puede transformar un 5xx en un 200 con un JSON de error
Los endpoints BFF del frontend a menudo envuelven los backends y devuelven 200 si la comunicación se ha producido, aunque el backend haya fallado
Los endpoints GraphQL suelen devolver 200; los errores (errors) están en el campo errors[]

Desde la perspectiva del monitoreo clásico (código de estado HTTP) todo está OK. Desde la perspectiva de un cliente real, la API se ha roto.

Coincidencia de contenido: palabras clave

El complemento más sencillo del monitoreo HTTP es la coincidencia de palabra clave. Define una cadena que debe estar en la respuesta - si falta, llega una notificación.

Ejemplo para un endpoint de health check:

GET /api/health HTTP/1.1

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

Configure la coincidencia de palabra clave en "status":"ok". Si la base de datos cae y el endpoint devuelve "status":"degraded", el monitoreo lo detectará.

Coincidencia negativa: lo que no debería aparecer

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

"error" - error en el cuerpo
"maintenance" - modo de mantenimiento inesperado
"deprecated" - el endpoint de la API se ha marcado como obsoleto (deprecated)
Fragmentos de errores SQL: "SyntaxError", "undefined", "null pointer" - errores del backend que se filtran

Aserciones avanzadas

La coincidencia de texto plano tiene sus límites. Para un monitoreo de API serio son adecuadas las aserciones estructuradas sobre la estructura JSON (expresiones JSONPath) y las transacciones sintéticas de varios pasos (login -> endpoint protegido -> logout).

ePulz.io admite estas opciones directamente. El monitoreo multipaso / de API permite encadenar hasta 10 pasos (GET/POST/PUT/PATCH/DELETE/HEAD), verificar en cada paso el código de estado, el contenido y también el valor JSONPath, y guardar variables de la respuesta para los pasos siguientes. La función está disponible en los planes Profi y Business y se ejecuta en la región primaria. Para casos más sencillos en planes inferiores, puede combinar un monitor HTTP con un script auxiliar independiente que envíe el resultado a través de un monitor heartbeat.

Autenticación en el monitoreo

El endpoint monitoreado a menudo requiere autenticación. Opciones:

Bearer token en la cabecera Authorization - normalmente un token de monitoreo de larga duración sin expiración (hay que guardarlo de forma segura)
API key en el parámetro de la consulta - visible en los registros, no recomendado
Firma HMAC - timestamp + URL + hash del cuerpo firmados con un secreto compartido. Lo más seguro.
mTLS - certificado de cliente en el lado del monitoreo. Adecuado para API internas.

Aviso de seguridad: Para el monitoreo, cree una cuenta / token dedicado con permisos mínimos (endpoint de health de solo lectura, no un token de administrador). Rote el token con regularidad. Si el servicio de monitoreo se ve comprometido, no se filtrará todo el acceso a la API.

SLO del tiempo de respuesta

El tiempo de respuesta de la API es tan importante como el código HTTP. Un cliente con un timeout de 30 s no nota la diferencia entre "la API devuelve 200 en 25 s" y "la API ha terminado en timeout". Desde el punto de vista de la UX, ambos son malos.

Configure:

Hard timeout - tras 10-15 s el monitoreo anuncia DOWN
Soft threshold - un tiempo de respuesta entre 500-2000 ms = advertencia (rendimiento degradado)
Notificaciones de tendencia - notificación si el percentil 95 del tiempo de respuesta sube un 50 % en las últimas 24 h

Monitoreo por endpoint

Una API grande tiene decenas de endpoints. No monitoree solo /health - también ese puede mentir. Identifique 3-5 endpoints críticos:

Las operaciones de negocio más usadas (POST /api/orders, GET /api/dashboard)
Un endpoint de lectura que pruebe el acierto de caché (respuesta rápida)
Un endpoint de escritura con ida y vuelta a la base de datos
Un endpoint de integración externa (llama a un tercero - detecta caídas de dependencias)

Monitoree cada uno por separado. Así, durante un incidente, verá exactamente qué parte de la API ha caído.

Conclusión

El monitoreo de API no puede reducirse al código de estado HTTP. Un buen monitoreo combina estado + coincidencia de contenido + tiempo de respuesta + granularidad por endpoint + autenticación, para imitar fielmente a un cliente real - y no solo a un cliente HTTP.

Monitoreo de API con coincidencia de palabra clave

Código de estado + palabra clave en el contenido + tiempo de respuesta + cabeceras de autenticación. Granularidad por endpoint.

Iniciar el monitoreo →