Monitoreo de API y assertions JSON

Un HTTP 200 solo confirma que el servidor aceptó la petición. En APIs reales, basta un error de negocio, un despliegue fallido o un feature flag mal configurado para que el cuerpo de la respuesta ya no sea el esperado — mientras el monitor sigue en verde.

Las assertions JSON de StatusInspector te permiten definir reglas declarativas sobre el cuerpo de la respuesta: qué campos deben existir, qué valores deben tener y qué comparaciones numéricas deben cumplirse. Si una regla falla, el check se trata como fallo operativo igual que un timeout o un código 500.

Disponibilidad según plan

Las assertions JSON avanzadas están disponibles en los planes Pro y Enterprise. En el plan Gratuito puedes seguir usando las comprobaciones básicas del monitor HTTP: código de respuesta esperado, palabra clave en el cuerpo y validación de Content-Type.

Cómo funcionan las assertions

El probe ejecuta un único request al endpoint configurado (con el método, cabeceras, cuerpo y autenticación que hayas definido).
Si el cuerpo de la respuesta es JSON válido, se decodifica y se aplican las reglas en orden.
La primera regla que no se cumple hace fallar el check — enfoque fail-fast. El error indica qué regla falló y por qué, sin exponer el cuerpo completo en logs ni alertas.
Si todas las reglas pasan, el check se evalúa como UP (salvo que la latencia supere el umbral configurado, en cuyo caso sería DEGRADED).

Esto evita la situación de "está verde en el balanceador y roto en negocio".

Cuándo un 200 no es suficiente

Situación	¿200?	Lo que hace el monitor con assertions
El endpoint devuelve `{ "error": "db_timeout" }`	Sí	Exige ausencia del campo `error` o presencia de `status: "ok"`
La lista de items llega vacía: `"items": []`	Sí	Usa `gt` para verificar que la longitud o un conteo es mayor que cero
La versión de API bajó: `"apiVersion": 1` en lugar de 2	Sí	Usa `gte` para confirmar que el valor es al menos 2
El cuerpo no es JSON o está truncado	A veces	Falla en la fase de parseo antes de evaluar las reglas

Sintaxis de rutas (path)

Las reglas se aplican sobre un path dentro del JSON, usando notación punto para acceder a campos anidados:

status                  → campo en la raíz
data.user.id            → campo id dentro de user dentro de data
items.0.name            → primer elemento del array items, campo name

Ejemplos de respuesta y sus paths:

{
  "status": "ok",
  "data": {
    "user": { "id": 42, "active": true }
  },
  "items": [
    { "name": "primer item" }
  ]
}

Path	Valor accedido
`status`	`"ok"`
`data.user.id`	`42`
`data.user.active`	`true`
`items.0.name`	`"primer item"`

nota

Los campos cuyo nombre contiene puntos u otros caracteres especiales no están soportados en la notación actual. Si tu API usa ese tipo de claves, considera si puedes validarlo con una comprobación de texto en el cuerpo.

Operadores disponibles

Operador	Descripción	Requiere `value`
`exists`	El path existe en el JSON	No
`not_exists`	El path no existe	No
`equals`	El valor en el path es igual al esperado	Sí
`not_equals`	El valor en el path es diferente al esperado	Sí
`contains`	El valor (string) contiene el texto esperado como subcadena	Sí
`gt`	El valor numérico es mayor que el esperado	Sí
`gte`	El valor numérico es mayor o igual que el esperado	Sí
`lt`	El valor numérico es menor que el esperado	Sí
`lte`	El valor numérico es menor o igual que el esperado	Sí

Las reglas se evalúan en el orden en que las defines. El panel te permite reordenarlas.

Ejemplos de configuración

Health check mínimo

Quieres confirmar que el servicio declara explícitamente que está operativo:

{ "status": "ok" }

Regla: equals sobre status con valor "ok".

Campo anidado

Respuesta típica de una API con estructura anidada:

{ "data": { "user": { "id": 42 } } }

Reglas sugeridas:

exists sobre data.user.id — confirma que el campo existe.
gt sobre data.user.id con valor 0 — confirma que el id es válido.

Verificar ausencia de error

Una API que devuelve 200 pero incluye un campo de error cuando algo falla:

{ "result": "ok", "error": null }

Regla: not_exists sobre error — o bien equals sobre result con valor "ok".

Control de versión

{ "version": 3, "deprecated": false }

Reglas:

gte sobre version con valor 2 — la versión es al menos 2.
equals sobre deprecated con valor false — el endpoint no está marcado como deprecado.

Assertions fallidas: DOWN, no DEGRADED

Cuando una assertion falla, el resultado del check es DOWN. El estado DEGRADED se reserva exclusivamente para casos de latencia alta: si el cuerpo es válido y todas las reglas pasan, pero la respuesta tardó más del umbral configurado.

No existe actualmente la posibilidad de marcar una assertion individual como "advertencia" que derive en DEGRADED en lugar de DOWN. Ver Estados del monitor.

Buenas prácticas

Prioriza la claridad sobre la exhaustividad. Define reglas que expresen un SLO claro — por ejemplo, "el campo ready existe y es true" — en lugar de validar cada campo posible de la respuesta.
Ajusta el timeout al comportamiento real de tu API. Timeouts demasiado bajos generan ruido; demasiado altos retrasan la detección de problemas reales.
Empieza con 1-3 reglas críticas y añade más a medida que entiendes los patrones de fallo de tu API.
Los secretos de autenticación son seguros. Las credenciales se cifran y nunca se exponen en texto claro en el panel, los logs ni las alertas.

Disponibilidad según plan​

Cómo funcionan las assertions​

Cuándo un 200 no es suficiente​

Sintaxis de rutas (path)​

Operadores disponibles​

Ejemplos de configuración​

Health check mínimo​

Campo anidado​

Verificar ausencia de error​

Control de versión​

Assertions fallidas: DOWN, no DEGRADED​

Buenas prácticas​

Próximos pasos​