Monitorização de API: como verificar a resposta JSON, não apenas HTTP 200

Em resumo: Uma API JSON pode devolver HTTP 200 com corpo {"status":"error","message":"DB unavailable"} - a monitorização que observa apenas o status code anuncia "UP". A verdadeira monitorização de API verifica também o conteúdo da resposta, não apenas a camada HTTP.

O problema: HTTP 200 != API a funcionar

As convenções REST API dizem para usar os status codes corretamente (200 OK, 4xx client error, 5xx server error). Na prática:

• Algumas APIs devolvem sempre 200, o erro está no body JSON
• Uma API gateway pode transformar 5xx em 200 com error JSON
• Os endpoints frontend BFF muitas vezes envolvem backends e devolvem 200 se a comunicação ocorreu, mesmo se o backend falhou
• Os endpoints GraphQL devolvem sempre 200, os erros estão no campo errors[]

Da perspetiva da monitorização clássica (status code HTTP) tudo está OK. Da perspetiva do cliente real a API está partida.

Content matching: palavras-chave

O complemento mais simples à monitorização HTTP é o keyword match. Defines uma string que tem de estar na resposta - se falta, alerta.

Exemplo para endpoint health check:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Configura keyword match para "status":"ok". Se a DB cai e o endpoint devolve "status":"degraded", a monitorização apanha.

Negative matching: o que devia faltar

Por vezes é mais útil verificar que uma determinada string NÃO está na resposta:

• "error" - erro no body
• "maintenance" - modo maintenance inesperado
• "deprecated" - endpoint API tornou-se deprecated
• fragmentos de erro SQL: "SyntaxError", "undefined", "null pointer" - erros backend a vazar

Asserções avançadas - roadmap

Match de texto simples tem limites. Para monitoramento API sério, são apropriadas asserções estruturadas sobre estrutura JSON (expressões JSONPath) e transações sintéticas multi-step (login -> endpoint protegido -> logout).

As asserções JSONPath e transações sintéticas multi-step estão na roadmap do ePulz.io mas atualmente não estão implementadas. Se precisar delas hoje, combine um monitor HTTP ePulz.io com seu próprio script que envia o resultado através de um monitor heartbeat (em caso de falha simplesmente não envie o heartbeat).

Authentication na monitorização

O endpoint monitorizado muitas vezes requer auth. Opções:

• Bearer token no header Authorization - tipicamente token de monitorização long-lived sem expiração (tem de ser guardado em segurança)
• Chave API em parâmetro query - visível em logs, não preferido
• Assinatura HMAC - timestamp + URL + hash do body assinado com shared secret. Mais seguro.
• mTLS - cert cliente do lado da monitorização. Adequado para APIs internas.

Aviso de segurança: Para monitorização cria conta / token dedicado com permissões mínimas (endpoint health read-only, não token admin). Roda o token regularmente. Se o serviço de monitorização vaza, não vaza todo o acesso à API.

Response time SLO

O response time da API é tão importante como o código HTTP. Um cliente com timeout 30 s não vê diferença entre "API devolve 200 em 25 s" e "API fez timeout". Em termos UX ambos são maus.

Configura:

• Hard timeout - após 10-15 s a monitorização anuncia DOWN
• Soft threshold - response time entre 500-2000 ms = warning (degraded performance)
• Trending alerts - alerta se o 95º percentil do response time subir 50% nas últimas 24 h

Monitorização por endpoint

Uma API grande tem dezenas de endpoints. Não monitorizes apenas /health - até ele pode mentir. Identifica 3-5 endpoints críticos:

• Operações de negócio mais usadas (POST /api/orders, GET /api/dashboard)
• Endpoint read para cache hit (resposta rápida)
• Endpoint write com roundtrip DB
• Endpoint de integração externa (chama terceiro - deteta quedas de dependências)

Monitoriza cada um separadamente. Durante um incidente vês exatamente que parte da API caiu.

Conclusão

A monitorização de API não pode ser reduzida ao status code HTTP. Monitorização de qualidade combina status + content match + response time + granularidade por endpoint + authentication, para se assemelhar a um cliente real - não apenas a um cliente HTTP.

Monitorização de API com keyword match

Status code + keyword no conteúdo + response time + auth headers. Granularidade por endpoint.

Experimentar durante 7 dias →