Salud
Endpoints de salud, liveness y readiness sin autenticación para monitorear la API de Tokeflow y sus dependencias.
Los endpoints de salud informan si la API de Tokeflow está en ejecución y si sus dependencias son accesibles. Úselos para monitoreo de uptime, comprobaciones de salud de balanceadores de carga y probes de orquestador — /health/live y /health/ready se corresponden directamente con los probes de liveness y readiness al estilo Kubernetes.
Estos endpoints se comportan de forma diferente al resto de la API. No requieren ninguna autenticación y no envuelven sus respuestas en el envelope estándar success/data: el cuerpo es un informe de salud simple, y el código de estado HTTP transporta el veredicto — 200 cuando todo funciona correctamente, 503 cuando alguna verificación falla.
Como el código de estado HTTP por sí solo indica si el servicio está saludable, la mayoría de los sistemas de monitoreo solo necesitan verificar un 200. Analice el cuerpo cuando quiera saber cuál dependencia está fallando.
El objeto de informe de salud
Los tres endpoints devuelven el mismo formato de informe:
| Campo | Tipo | Descripción |
|---|---|---|
status | string | Resultado general — ok cuando todas las verificaciones pasan, error cuando al menos una falla. |
info | object | null | Verificaciones que actualmente están saludables, indexadas por el nombre de la verificación. Cada entrada contiene al menos un campo status. |
error | object | null | Verificaciones que actualmente están fallando, indexadas por el nombre de la verificación. Cada entrada contiene al menos un campo status, además de detalles adicionales como un message. Vacío cuando todo está saludable. |
details | object | Todas las verificaciones, saludables o no, indexadas por el nombre de la verificación — la unión de info y error. Cada entrada contiene al menos un campo status. |
Las claves dentro de info, error y details son los nombres de las verificaciones individuales (por ejemplo, database). Cada entrada de verificación siempre tiene un status (up o down) y puede llevar campos adicionales que describen el fallo.
Endpoints
GET/api/v1/health
Auth: Ninguna. Este endpoint es de acceso público — no se requiere ninguna clave de API.
Ejecuta la verificación de salud completa: el proceso de la API más sus dependencias de backend. Devuelve 200 con todas las verificaciones bajo info cuando el servicio está saludable, o 503 con las verificaciones fallidas bajo error cuando no lo está.
Example request
curl https://api.tokeflow.com/api/v1/healthExample response — 200 OK
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
},
"error": {},
"details": {
"database": {
"status": "up"
}
}
}Example response — 503 Service Unavailable
{
"status": "error",
"info": {
"database": {
"status": "up"
}
},
"error": {
"cache": {
"status": "down",
"message": "Could not connect"
}
},
"details": {
"database": {
"status": "up"
},
"cache": {
"status": "down",
"message": "Could not connect"
}
}
}GET/api/v1/health/live
Auth: Ninguna. Este endpoint es de acceso público — no se requiere ninguna clave de API.
Probe de liveness: informa si el propio proceso de la API está en ejecución y puede responder. Dirija aquí las verificaciones orientadas a reinicio — si este endpoint deja de devolver 200, el proceso debería reiniciarse.
Example request
curl https://api.tokeflow.com/api/v1/health/liveExample response — 200 OK
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
},
"error": {},
"details": {
"database": {
"status": "up"
}
}
}GET/api/v1/health/ready
Auth: Ninguna. Este endpoint es de acceso público — no se requiere ninguna clave de API.
Probe de readiness: informa si el servicio está listo para recibir tráfico, incluyendo el estado de sus dependencias. Dirija aquí las verificaciones que controlan el tráfico — un balanceador de carga u orquestador debería dejar de enrutar solicitudes a una instancia mientras este endpoint devuelva 503, sin reiniciarla.
Example request
curl https://api.tokeflow.com/api/v1/health/readyExample response — 200 OK
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
},
"error": {},
"details": {
"database": {
"status": "up"
}
}
}Example response — 503 Service Unavailable
{
"status": "error",
"info": {
"database": {
"status": "up"
}
},
"error": {
"cache": {
"status": "down",
"message": "Could not connect"
}
},
"details": {
"database": {
"status": "up"
},
"cache": {
"status": "down",
"message": "Could not connect"
}
}
}Errores
Los endpoints de salud no usan el envelope de error estándar. Solo existen dos resultados posibles:
| HTTP | Significado |
|---|---|
200 | Todas las verificaciones pasaron. status es ok y error está vacío. |
503 | Una o más verificaciones fallaron. status es error y las verificaciones fallidas aparecen bajo error (y details). |
Para el envelope usado por el resto de los endpoints, consulte Errors.
Relacionados
- Errors — el envelope de error estándar usado por el resto de la API.
- Authentication — cómo los endpoints autenticados verifican sus claves de API.
- How Tokeflow works — la arquitectura de orquestación que estas verificaciones monitorean.