Cómo monitorizar una API REST en cuanto a uptime y tiempo de respuesta

Monitorizar una API REST no es lo mismo que monitorizar un sitio web. Un HTTP 200 exitoso de tu API no garantiza que la respuesta sea correcta, que el tiempo de respuesta sea aceptable o que la autenticación siga funcionando. Esta guía cubre lo que un monitor de API debería comprobar realmente, los umbrales que detectan problemas a tiempo sin generar ruido y los modos de fallo silenciosos que las simples comprobaciones de ping pasan por alto.

Las cuatro cosas que un monitor de API debe comprobar

Un monitor de API útil comprueba cuatro cosas en cada sondeo. Cada una detecta una clase distinta de fallo que las demás pasarían por alto.

Código de estado: ¿la API devolvió 200, o devolvió 500, 502 o 503? Tiempo de respuesta: ¿la API respondió dentro de una ventana aceptable? Contenido del cuerpo: ¿la respuesta contiene los campos esperados? Estado de autenticación: ¿la API sigue aceptando las credenciales que aceptaba ayer? Un monitor que comprueba las cuatro detecta comportamientos anómalos que cualquier comprobación aislada pasaría por alto.

Los endpoints que merece la pena monitorizar

No todos los endpoints de API necesitan un monitor. Tres categorías cubren la mayor parte del valor real.

• Un endpoint de salud: normalmente /health o /status. Debe devolver 200 con una pequeña carga útil JSON que confirme la conexión a la base de datos y cualquier dependencia crítica. Ligero para sondear, rápido para fallar cuando algo va mal.
• El endpoint real más utilizado: el que recibe la mayor fracción de tu tráfico. Si tu endpoint /users/me atiende el 80% de las solicitudes, monitorízalo directamente. Si deja de funcionar, tus clientes lo notarán de inmediato.
• El endpoint real de mayores ingresos: el que gestiona pagos, suscripciones o cualquier cosa que se traduzca directamente en dinero. Mismo monitor, mayor prioridad de alerta.

Cómo establecer umbrales de tiempo de respuesta sin falsas alarmas

Las alertas de tiempo de respuesta son la forma más fácil de producir un monitor ruidoso. Un único sondeo lento durante un despliegue no es señal; diez sondeos lentos seguidos sí lo son. La estrategia de umbrales que funciona se basa en percentiles, no en valores absolutos.

Mide el tiempo de respuesta p95 de tu endpoint durante una semana normal. Establece el umbral de alerta en 2x el p95. Alerta solo si tres sondeos consecutivos lo superan. El resultado es un monitor que ignora la variación normal pero detecta la degradación real. Ajusta el multiplicador y el número de umbrales durante el primer mes, y después déjalo en paz.

Los modos de fallo silencioso que las comprobaciones simples de ping no detectan

Una API puede devolver HTTP 200 y aun así estar rota. Cuatro fallos silenciosos comunes aparecen en incidentes reales.

• Respuestas de error en caché: la API devuelve correctamente 500 una vez, queda almacenada en caché en un CDN y, a partir de ese momento, sirve un 200 con un cuerpo de error obsoleto.
• Tipo de contenido incorrecto: la API devuelve HTML en lugar de JSON porque se dejó activado un middleware de depuración. El estado es 200, pero el cuerpo no se puede analizar.
• Éxito vacío: la API devuelve 200 con un conjunto de resultados vacío, porque la consulta subyacente perdió silenciosamente un join durante una migración.
• Deriva de autenticación: la API devuelve 200 porque el limitador de tasa maneja la solicitud no autenticada con elegancia, pero el cuerpo dice «inicia sesión, por favor».

Monitorización autenticada sin filtrar credenciales

Muchas API requieren autenticación en cada endpoint. El monitor necesita credenciales. Dos patrones funcionan bien; un patrón común supone un grave riesgo de seguridad.

Bueno: una clave de API dedicada de solo lectura con el alcance más reducido posible, rotada trimestralmente, almacenada cifrada en la herramienta de monitorización. Mejor: una firma de webhook o HMAC en lugar de un bearer token, para que el monitor no pueda suplantar a un usuario. Malo: un bearer token de larga duración para el usuario administrador de producción, pegado en la configuración del monitor. El tercer patrón genera sus propios incidentes cuando las credenciales del monitor se filtran.

La configuración inicial para una API

Añade tres monitores por API. Un monitor /health con una cadencia de 60 segundos y un umbral de tiempo de respuesta de 500 ms. Un monitor sobre el endpoint real más utilizado con una cadencia de 60 segundos y una aserción sobre el contenido del cuerpo. Un monitor sobre el endpoint de mayores ingresos con una cadencia de 30 segundos, la misma aserción del cuerpo y un umbral de tiempo de respuesta más estricto. Total de monitores: tres. Cobertura total: la mayor parte de lo que importa. Añade monitores específicos para casos extremos a medida que aparezcan en incidentes reales, no de forma preventiva.