Saúde
Endpoints de saúde, liveness e readiness não autenticados para monitorar a API da Tokeflow e suas dependências.
Os endpoints de saúde informam se a API da Tokeflow está em execução e se suas dependências estão acessíveis. Use-os para monitoramento de uptime, verificações de saúde de load balancer e probes de orquestrador — /health/live e /health/ready mapeiam diretamente para probes de liveness e readiness no estilo Kubernetes.
Esses endpoints se comportam de forma diferente do restante da API. Eles não exigem nenhuma autenticação e não encapsulam suas respostas no envelope padrão success/data: o corpo é um relatório de saúde puro, e o código de status HTTP carrega o veredito — 200 quando tudo está funcionando, 503 quando alguma verificação falha.
Como o código de status HTTP por si só informa se o serviço está saudável, a maioria dos sistemas de monitoramento só precisa verificar um 200. Analise o corpo quando quiser saber qual dependência está falhando.
O objeto de relatório de saúde
Os três endpoints retornam o mesmo formato de relatório:
| Campo | Tipo | Descrição |
|---|---|---|
status | string | Resultado geral — ok quando todas as verificações passam, error quando pelo menos uma falha. |
info | object | null | Verificações que estão atualmente saudáveis, indexadas pelo nome da verificação. Cada entrada contém pelo menos um campo status. |
error | object | null | Verificações que estão atualmente falhando, indexadas pelo nome da verificação. Cada entrada contém pelo menos um campo status, além de detalhes extras como uma message. Vazio quando tudo está saudável. |
details | object | Todas as verificações, saudáveis ou não, indexadas pelo nome da verificação — a união de info e error. Cada entrada contém pelo menos um campo status. |
As chaves dentro de info, error e details são os nomes das verificações individuais (por exemplo, database). Cada entrada de verificação sempre tem um status (up ou down) e pode carregar campos adicionais descrevendo a falha.
Endpoints
GET/api/v1/health
Auth: Nenhuma. Este endpoint é publicamente acessível — não é necessária nenhuma chave de API.
Executa a verificação de saúde completa: o processo da API mais suas dependências de backend. Retorna 200 com todas as verificações em info quando o serviço está saudável, ou 503 com as verificações que falharam em error quando não 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: Nenhuma. Este endpoint é publicamente acessível — não é necessária nenhuma chave de API.
Probe de liveness: informa se o próprio processo da API está em execução e é capaz de responder. Aponte para cá as verificações orientadas a reinício — se este endpoint parar de retornar 200, o processo deve ser reiniciado.
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: Nenhuma. Este endpoint é publicamente acessível — não é necessária nenhuma chave de API.
Probe de readiness: informa se o serviço está pronto para receber tráfego, incluindo o estado de suas dependências. Aponte para cá as verificações que controlam o tráfego — um load balancer ou orquestrador deve parar de rotear requisições para uma instância enquanto este endpoint retornar 503, sem reiniciá-la.
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"
}
}
}Erros
Os endpoints de saúde não usam o envelope de erro padrão. Existem apenas dois resultados possíveis:
| HTTP | Significado |
|---|---|
200 | Todas as verificações passaram. status é ok e error está vazio. |
503 | Uma ou mais verificações falharam. status é error e as verificações que falharam aparecem em error (e details). |
Para o envelope usado por todos os demais endpoints, consulte Errors.
Relacionados
- Errors — o envelope de erro padrão usado pelo restante da API.
- Authentication — como os endpoints autenticados verificam suas chaves de API.
- How Tokeflow works — a arquitetura de orquestração que essas verificações monitoram.