Saltar al contenido principal

Assertions JSON para APIs

Las assertions JSON permiten verificar que la respuesta de tu API contiene los datos correctos, no solo que responde con el código HTTP esperado. Esta guía complementa la documentación del monitor HTTP/Web con ejemplos avanzados.

Sintaxis de path​

Los paths usan notación de punto para navegar el JSON:

JSONPath
{"status": "ok"}status
{"data": {"id": 42}}data.id
{"items": [{"name": "a"}]}items.0.name
{"meta": {"pagination": {"total": 100}}}meta.pagination.total

Operadores disponibles​

Existencia​

{"type": "json_exists", "path": "data.id"}

El check falla si data.id no existe en la respuesta.

{"type": "json_exists", "path": "errors"}

Con operador inverso not_exists (disponible en el modo clásico de assertions HTTP).

Igualdad​

{"type": "json_equals", "path": "status", "value": "ok"}
{"type": "json_equals", "path": "data.active", "value": true}

Comparación numérica​

{"type": "json_gt", "path": "meta.total", "value": 0}

El check falla si meta.total no es mayor que 0.

{"type": "json_gte", "path": "data.score", "value": 7.5}
{"type": "json_lt", "path": "queue.size", "value": 1000}

Regex (PCRE)​

{"type": "json_regex", "path": "data.email", "value": "/^[^@]+@[^@]+$/"}

El valor en el path debe cumplir el patrón PCRE. Longitud máxima del patrón: 256 caracteres.

{"type": "json_regex", "path": "data.version", "value": "/^\\d+\\.\\d+\\.\\d+$/"}

Assertions de cabeceras HTTP​

También puedes validar cabeceras de respuesta:

{"type": "header_equals", "header": "content-type", "value": "application/json"}
{"type": "header_contains", "header": "x-powered-by", "value": "Express"}

Assertions de latencia​

{"type": "latency_lt", "value": 500}

El paso falla si la latencia supera 500 ms. Útil en synthetic multi-step para garantizar SLOs por paso.

Ejemplos completos​

Verificar una API de lista paginada​

[
  {"type": "http_code", "value": 200},
  {"type": "json_exists", "path": "data"},
  {"type": "json_gt", "path": "meta.pagination.total", "value": 0},
  {"type": "json_equals", "path": "meta.pagination.page", "value": 1}
]

Verificar creación de recurso​

[
  {"type": "http_code", "value": 201},
  {"type": "json_exists", "path": "data.id"},
  {"type": "json_equals", "path": "data.status", "value": "active"}
]

Verificar respuesta de health check​

[
  {"type": "http_code", "value": 200},
  {"type": "json_equals", "path": "status", "value": "ok"},
  {"type": "json_equals", "path": "database", "value": "connected"},
  {"type": "latency_lt", "value": 1000}
]

Verificar formato de respuesta con regex​

[
  {"type": "http_code", "value": 200},
  {"type": "json_regex", "path": "data.created_at", "value": "/^\\d{4}-\\d{2}-\\d{2}T/"}
]

Assertions en synthetic multi-step​

En flujos multi-paso, cada paso tiene sus propias assertions y puedes combinar todas las opciones anteriores. Además, puedes usar variables extraídas de pasos anteriores directamente en la URL del siguiente paso.

Ver Synthetic multi-step para el flujo completo.

Notas importantes​

  • Las assertions se evalúan en orden (fail-fast): la primera que falla detiene la evaluación del resto.
  • Una assertion fallida resulta en DOWN, no en DEGRADED (no hay severidad por assertion todavía).
  • El path debe apuntar a un valor escalar (string, número, booleano) para operadores de comparación; json_exists también funciona con objetos y arrays.