Monitorização de API: quando o HTTP 200 não chega

Uma API JSON pode devolver HTTP 200 com um corpo que descreve um erro - a monitorização baseada no código de estado declara UP. A verdadeira monitorização de API verifica também o conteúdo da resposta, não apenas o HTTP.

Problema: HTTP 200 ≠ API funcional

Segundo as convenções das API REST, os códigos de estado devem ser usados corretamente (200 OK, 4xx erro do cliente, 5xx erro do servidor). Na prática:

Algumas API devolvem sempre 200 e o erro está no corpo JSON
Um API gateway pode transformar um 5xx num 200 com JSON de erro
Os endpoints frontend BFF muitas vezes envolvem os backends e devolvem 200 se a comunicação ocorreu, mesmo que o backend tenha falhado
Os endpoints GraphQL devolvem tipicamente 200; os erros (errors) estão no campo errors[]

Da perspetiva da monitorização clássica (código de estado HTTP) está tudo OK. Da perspetiva de um cliente real, a API ficou avariada.

Content matching: palavras-chave

O complemento mais simples da monitorização HTTP é a correspondência de palavra-chave. Define uma cadeia de carateres que tem de estar na resposta - se faltar, chega uma notificação.

Exemplo para um endpoint de health check:

GET /api/health HTTP/1.1

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

Configure a correspondência de palavra-chave para "status":"ok". Se a base de dados cair e o endpoint devolver "status":"degraded", a monitorização deteta-o.

Negative matching: o que deve faltar

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

"error" - erro no corpo
"maintenance" - modo de manutenção inesperado
"deprecated" - o endpoint da API foi marcado como obsoleto (deprecated)
Fragmentos de erros SQL: "SyntaxError", "undefined", "null pointer" - erros de backend a transparecer

Asserções avançadas

A correspondência de texto simples tem os seus limites. Para uma monitorização de API séria, são adequadas as asserções estruturadas sobre a estrutura JSON (expressões JSONPath) e as transações sintéticas de vários passos (login -> endpoint protegido -> logout).

O ePulz.io suporta estas possibilidades diretamente. A monitorização multi-step / de API permite encadear até 10 passos (GET/POST/PUT/PATCH/DELETE/HEAD), verificar em cada passo o código de estado, o conteúdo e também o valor JSONPath, e guardar variáveis da resposta para os passos seguintes. A funcionalidade está disponível nos planos Profi e Business e corre na região primária. Para casos mais simples nos planos inferiores, pode combinar um monitor HTTP com um script auxiliar separado que envia o resultado através de um monitor heartbeat.

Autenticação na monitorização

O endpoint monitorizado exige muitas vezes autenticação. Opções:

Bearer token no cabeçalho Authorization - tipicamente um monitoring token de longa duração sem expiração (deve ser guardado de forma segura)
API key num parâmetro de query - visível nos logs, não recomendado
Assinatura HMAC - timestamp + URL + hash do corpo assinados com um shared secret. A opção mais segura.
mTLS - certificado de cliente do lado da monitorização. Adequado para API internas.

Aviso de segurança: Para a monitorização, crie uma conta / token dedicado com privilégios mínimos (endpoint de health só de leitura, não um token de admin). Rode o token regularmente. Se o serviço de monitorização vazar, não fica exposto todo o acesso à API.

SLO do tempo de resposta

O tempo de resposta da API é tão importante como o código HTTP. Um cliente com timeout de 30 s não vê diferença entre "a API devolve 200 em 25 s" e "a API terminou em timeout". Do ponto de vista da UX, ambos são maus.

Configure:

Hard timeout - ao fim de 10-15 s a monitorização reporta DOWN
Soft threshold - tempo de resposta entre 500-2000 ms = aviso (desempenho degradado)
Notificações de tendência - notificação se o percentil 95 do tempo de resposta subir 50 % nas últimas 24 h

Monitorização por endpoint

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

As business operations mais usadas (POST /api/orders, GET /api/dashboard)
Um endpoint de leitura que testa o cache hit (resposta rápida)
Um endpoint de escrita com roundtrip à base de dados
Um endpoint de integração externa (chama um terceiro - deteta falhas de dependências)

Monitorize cada um separadamente. Assim, durante um incidente, vê com precisão qual parte da API caiu.

Conclusão

A monitorização de API não pode ser reduzida ao código de estado HTTP. Uma monitorização de qualidade combina estado + content match + tempo de resposta + granularidade por endpoint + autenticação, para imitar fielmente um cliente real - e não apenas um cliente HTTP.

Monitorização de API com correspondência de palavra-chave

Código de estado + palavra-chave no conteúdo + tempo de resposta + auth headers. Granularidade por endpoint.

Iniciar a monitorização →