Documentación

Sepa que su API responde bien, no solo que responde

La mayoría de los fallos de una API no parecen fallos para una comprobación del código de estado. El framework captura la excepción y responde 200 OK con {"error": "database unavailable"}. Una importación fallida deja vacía la lista de productos. Una caché sigue sirviendo datos de antes de que se parara el proceso que la alimenta. En todos estos casos la API está «disponible» y, sin embargo, no funciona para ningún cliente que la llame.

Pingsured lee el JSON de la respuesta y comprueba los valores que indican si la API funciona de verdad.

Qué comprobar

Un endpoint de health check que informa del estado de sus dependencias es el punto de partida más sencillo. Si responde {"status": "ok", "db": "ok", "queue": {"depth": 12}}:

La última línea es la que un código de estado nunca puede darle: la API está disponible y el trabajo que hay detrás no se está acumulando.

Para un endpoint que devuelve datos en lugar de un estado, compruebe la forma de los propios datos:

Una lista vacía, un precio de cero y una respuesta de hace más de quince minutos hacen fallar el ping, aunque el servidor siga respondiendo 200.

Endpoints que requieren credenciales

Añada las cabeceras que espera la API (un token Authorization: Bearer, una cabecera con la clave de API) o autenticación HTTP básica. Dé a la comprobación un token propio que solo pueda leer: se guarda con el ping, y un token creado para la monitorización puede revocarse sin romper nada más.

Por qué comprobar su API con Pingsured

• Comparaciones con tipo. El número 12 no es igual a la cadena "12", así que un cambio de serialización que convierte números en cadenas (y rompe todos los clientes con tipado estricto) hace fallar la comprobación en lugar de pasar desapercibido.
• Actualidad sin scripts. Los operadores de antigüedad leen marcas de tiempo ISO 8601, fechas HTTP y tiempo Unix, de modo que «los datos tienen menos de una hora» es una línea, no un cron que a su vez tendría que monitorizar.
• Hasta 16 comprobaciones JSON por ping, combinables libremente con el código de estado, una comprobación de cabeceras y una búsqueda de texto. El ping solo es correcto cuando se cumplen todas.
• Comprobada desde donde están sus clientes. Cada ubicación se evalúa por separado, así que una API que falla tras un nodo de la CDN o desde una región no queda oculta por las demás.
• Alertas donde trabaja. Por correo electrónico y en la aplicación; a partir del plan Team, también mediante un webhook a su herramienta de incidencias o su chat.
• Los datos de su API se quedan en la UE. Endpoints, cabeceras y tokens forman parte de lo que guarda una cuenta de monitorización. Pingsured los almacena en Alemania y Finlandia, sin ningún servicio estadounidense de por medio.

Límites que conviene conocer

• Las comprobaciones envían GET o HEAD. Una API a la que solo se accede con POST (la mayoría de las instalaciones GraphQL, SOAP) todavía no puede comprobarse.
• Cada comprobación es una única solicitud. No es posible un flujo que primero inicie sesión y luego llame a la API con la sesión obtenida; un token de larga duración en una cabecera, sí.
• La respuesta se lee hasta 1 MB, y un JSON cortado en ese punto ya no se puede analizar. Apunte la comprobación a un endpoint pequeño o a una página de una lista, no a una exportación completa.