Documentación

Monitorización de API: comprobar JSON, XML, HTML y cabeceras

Un servidor que responde 200 OK con una página de error, una lista vacía o los datos de ayer está disponible a juzgar por cualquier código de estado y, sin embargo, no le sirve de nada a quien lo usa. Pingsured puede comprobar qué contiene una respuesta, no solo que haya llegado.

Todas las comprobaciones siguientes son opcionales y puede combinarlas libremente. Un ping solo se considera correcto cuando el código de estado coincide y se cumplen todas las comprobaciones de contenido que haya configurado.

Código de estado

El estado esperado puede ser un único código, una lista o un rango: 200, 200,204 o 200-299. Cualquier otro se considera un fallo. El valor predeterminado es 200.

Texto en el cuerpo

La comprobación de contenido más sencilla: el cuerpo de la respuesta debe contener un texto concreto, como el nombre de un producto o la marca de «en buen estado» que imprime su endpoint de salud. Se busca como subcadena simple, de hasta 1024 caracteres.

Campos JSON (JSONPath)

Para monitorizar una API, seleccione un valor con una expresión JSONPath y compárelo. Por ejemplo, un endpoint de salud que responde {"status": "ok", "queue": {"depth": 12}} puede comprobarse así:

Operadores disponibles:

• existe / no existe: la ruta selecciona algo, o nada.
• igual a / distinto de: con tipo; el número 12 no es igual a la cadena "12".
• contiene y coincide con (una expresión regular) para texto.
• mayor / menor que (o igual) para números.
• recuento: comparaciones sobre el número de coincidencias, como «al menos un elemento en $.items[*]».
• antigüedad: comparaciones para marcas de tiempo, descritas más abajo en el apartado sobre la actualidad de los datos.

Cuando una ruta selecciona varios valores, se compara el primero. Hasta 16 comprobaciones JSON por ping.

Elementos XML (XPath)

La misma idea para respuestas XML (feeds, servicios SOAP, sitemaps), con expresiones XPath como /rss/channel/item (recuento de al menos 1) o //status/text() (igual a ok). Los operadores son existe, no existe, igual a, contiene, coincide con, las comparaciones de recuento y las de antigüedad. Una respuesta que no sea XML bien formado no supera ninguna comprobación XML.

Elementos HTML (selectores CSS)

Para monitorizar una página web, elija un elemento con un selector CSS (o con una expresión XPath, si lo prefiere) y compruebe su texto o uno de sus atributos. El texto se compara con los espacios en blanco normalizados, así que los saltos de línea del marcado no influyen. Usos habituales:

• el elemento del precio en una página de producto existe y no está vacío;
• h1.title contiene su titular, de modo que se detecta una plantilla en blanco o una página de mantenimiento;
• el atributo content de una etiqueta meta tiene el valor que debe tener.

Cabeceras de la respuesta

Hay dos formas de comprobar las cabeceras: una coincidencia exacta por cabecera, o los mismos operadores de arriba (existe, no existe, igual a, contiene, coincide con, comparaciones numéricas y antigüedad). Las comprobaciones de cabeceras no leen el cuerpo.

Actualidad: ¿están los datos al día?

Los operadores de antigüedad interpretan un valor como marca de tiempo y comparan su antigüedad en segundos. «$.updated_at antigüedad menor que 3600» falla en cuanto los datos más recientes tienen más de una hora: el caso clásico de una exportación, una caché o un feed que ha dejado de actualizarse sin que nadie lo note mientras el servidor sigue respondiendo.

Formatos reconocidos:

• ISO 8601 / RFC 3339, como 2026-10-09T14:30:00Z (una hora sin zona horaria se interpreta como UTC);
• fechas HTTP, de modo que una cabecera Last-Modified funciona tal cual;
• tiempo Unix en segundos o en milisegundos.

Límites que conviene conocer

• El cuerpo se lee hasta 1 MB.
• Las comprobaciones envían solicitudes GET o HEAD. Otros métodos y los cuerpos de solicitud todavía no están disponibles: pueden modificar datos en el servidor comprobado, por lo que antes exigirán demostrar que el dominio es suyo.
• Puede añadir hasta 20 cabeceras de solicitud y autenticación HTTP básica, para endpoints que requieren un token o un inicio de sesión.
• El User-Agent es siempre Pingsured/1.0, con un enlace a la página que explica nuestras solicitudes a los operadores de servidores.