Supervisión de API

Por qué una API necesita su propia monitorización

Una API no es simplemente una página en /api/. Es un contrato. El método HTTP importa: GET vs POST cambia la semántica. Las cabeceras llevan autenticación, negociación de contenido, claves de idempotencia. El body de la petición es la entrada. El código de respuesta importa (401 vs 403 vs 422: cada uno cuenta una historia distinta). El body de respuesta tiene estructura: rutas JSON de las que dependen los integradores. Un simple chequeo de disponibilidad, que solo hace GET a la URL, pasará por alto la mayoría de las formas en las que una API puede fallar: JSON incorrecto que aún responde 200, endpoint de autenticación aceptando datos inválidos, un webhook con esquema de payload roto, endpoint respondiendo 200 pero con "status": "error" en el interior.

La monitorización de la API soluciona esto dándote control sobre cada parte de la petición y cada parte de la verificación de la respuesta. Configuras exactamente la llamada que hacen tus integradores: mismo método, mismas cabeceras, mismo body, misma autenticación, y exactamente lo que significa éxito: códigos exactos, valores en ciertas rutas JSON, umbrales de tiempo de respuesta, límites de tamaño.

Configuración de la petición

Para cada monitor de API en DiagnoSEO Uptime Monitoring puedes configurar:

• Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Elige el que usan tus integradores.
• Cabeceras personalizadas: como objeto JSON, p. ej. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Estándar para probar OAuth, JWT, claves API, negociación de contenido.
• Body de la petición: cualquier string – JSON, XML, form-encoded, texto plano. Enviado en POST/PUT/PATCH/DELETE.
• Basic auth: usuario y contraseña, si el endpoint está protegido así.
• Códigos de estado esperados: lista o rango. Por defecto 200-399, pero puedes restringirlo a un solo código (p. ej. exactamente 201 para endpoints de creación) o permitir concretos (p. ej. 200,202,204).

El chequeo sigue hasta 5 redirecciones, decodifica gzip, analiza el Content-Type para detectar JSON. Cada chequeo registra el código real, tiempo de respuesta, tamaño y cualquier error. Varias fallas sucesivas (configurable, por defecto 2) disparan un incidente.

Aserciones de rutas JSON

Los códigos de estado por sí solos no bastan para muchas APIs. Un endpoint de salud puede devolver 200 con body {"status": "degraded", "db": "down"} – sigue siendo 200, pero absolutamente quieres saberlo. Una API de precios puede devolver 200 con body donde data.price es null. Una API de buscador puede responder 200 con results: [] porque el índice está caído.

Para esos casos, configura una aserción de ruta JSON. Define la ruta (p. ej. data.status o health.checks.db) y el valor esperado (p. ej. healthy, true o un número concreto). En cada chequeo se decodifica la respuesta como JSON y se compara el valor en la ruta. Un desajuste da por fallido el chequeo aunque el HTTP status sea correcto.

La sintaxis de la ruta es notación de punto con corchetes: data.items[0].id funciona, igual que users.john.email. El valor a asertar se compara como string, así "true" casa con booleano true, y los números casan tanto como string como número.

Patrones de autenticación

Los dos estilos auth más comunes funcionan directamente. Para tokens Bearer (OAuth, JWT, claves API) usa el campo headers: {"Authorization": "Bearer eyJhbGciOi..."}. El token está en la configuración del monitor y se envía en cada chequeo. Para basic auth usa los campos dedicados usuario/contraseña – se guardan y combinan en el header estándar.

Si la autenticación requiere firmar por cada petición o refrescar el token, es más complicado. Dos patrones razonables: (1) configura un token de servicio de larga duración solo para monitorización, o (2) habilita un endpoint de health no autenticado que refleje el estado del protegido real, y monitorízalo. La mayoría de APIs modernas ya traen esto de serie.

Patrones recomendados

• Un monitor por endpoint crítico. No testees todos: elige 5-10 cuya caída supondría un daño real.
• Usa códigos exactos. Por defecto 200-399 es demasiado permisivo para una API. Un endpoint de creación debería responder exactamente 201; un idempotente, exactamente 200; uno de login, exactamente 200 (éxito) o 401 (fallo bien formado – no 500).
• Combina estado con aserción JSON. Juntos atrapan regresiones de capa de transporte y de contenido. Solo el estado no atrapa errores de contenido; solo la aserción JSON resulta frágil ante redirecciones.
• Fija un umbral de tiempo de respuesta. La degradación de la API es indicio temprano de problemas con dependencias. Un monitor con rt_threshold_ms = 800 indica que la API se está ralentizando antes de caerse.
• Mantén los bodies pequeños. El chequeo es cada minuto: bodies grandes desperdician ancho de banda en ambos lados. Payloads representativos pero mínimos bastan.

Combina con otros tipos de monitores

Para cada endpoint de API, el monitor API verifica que la llamada funciona. Un monitor ping o de puerto aparte verifica que el host vive. Un chequeo SSL/dominio en ese host captura problemas de certificado y registro. Un submonitor de DNS vigila cambios en los registros que puedan indicar un secuestro. Juntos, cuatro monitores sobre la API te dan visión completa con solapamiento mínimo.

Configuración

Abre la herramienta, haz clic en "Añadir monitor", elige tipo "API". Pega la URL. Abre la sección Avanzada. Elige el método, pega las cabeceras como JSON, pega el body si hace falta, pon basic auth si lo usas, escribe los códigos esperados (p. ej. 200 o 200,201). Añade aserción JSON path si aplica. Establece el intervalo y el umbral de confirmación. Guarda. Desde el siguiente ciclo el monitor llamará a tu API exactamente como lo haría un integrador, valida la respuesta y alerta al segundo de cualquier regresión.

Preguntas frecuentes

• ¿Qué métodos HTTP puedo usar para monitorizar una API?

  GET, POST, PUT, DELETE, PATCH y HEAD. Configura el método por monitor — para endpoints de escritura (POST/PUT/PATCH) el body también se puede configurar como string JSON o form data.

• ¿Cómo funcionan las aserciones JSON?

  Indicas la ruta JSON (p. ej. data.status o results[0].id) y el valor esperado. El monitor recoge la respuesta, la convierte a JSON, extrae la ruta y la compara con lo esperado. Si no coincide, el chequeo falla con error "assertion failed" mostrando el valor real.

• ¿Puedo enviar cabeceras de autenticación?

  Sí. Las cabeceras HTTP personalizadas se pueden configurar por monitor — tokens Authorization, claves API, content-type, lo que sea. Los valores de las cabeceras se cifran en reposo en la base de datos. Para Basic Auth hay un campo dedicado de usuario/contraseña que firma automáticamente la petición.

• ¿Qué pasa si mi API responde 200 con un payload de error?

  Un patrón común: la API devuelve HTTP 200 pero el body dice {"status":"error"}. Un monitor uptime ingenuo pensará que está sana. Usa una aserción JSON status == "ok" para detectarlo — la aserción falla y el monitor marca COMO CAÍDO pese a que el HTTP dice 200.

• ¿Cómo gestionar una API con limitación de tasa?

  Fija el intervalo de chequeos para respetar el límite de la API (p. ej. intervalo de 5 minutos si la API permite 12 llamadas/hora). El monitor cuenta como una llamada API por chequeo desde una región. Chequeos multi-región multiplican las llamadas — usa una única región si tu API tiene límites estrictos.