Monitoramento de API

Porque é que uma API precisa do seu próprio monitoramento

Uma API não é apenas uma página sob /api/. É um contrato. O método HTTP importa — GET vs POST muda a semântica. Os cabeçalhos transportam autenticação, negociação de conteúdo, chaves de idempotência. O corpo do pedido é a entrada. O código de resposta é relevante (401 vs 403 vs 422 — cada um conta uma história diferente). O corpo da resposta tem estrutura — caminhos JSON dos quais os integradores dependem. Um simples check de uptime, que só atinge o URL com GET, perde a maioria das formas como uma API pode falhar: JSON inválido ainda a devolver 200, endpoint de autenticação a aceitar dados errados, webhook com esquema de payload corrompido, endpoint a devolver 200 mas com "status": "error" no meio.

O monitoramento de API resolve isto ao dar-lhe controlo sobre cada parte do pedido e cada parte da verificação de resposta. Configura exatamente o call que os seus integradores fazem — o mesmo método, os mesmos cabeçalhos, o mesmo corpo, a mesma autenticação — e exatamente o que significa sucesso — códigos exatos, valores em caminhos JSON, limites de tempo de resposta, limites de tamanho.

Configuração do pedido

Para cada monitor de API no DiagnoSEO Uptime Monitoring pode configurar:

• Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Escolha aquele que os integradores usam.
• Cabeçalhos personalizados: como um objeto JSON, por ex. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Padrão para testar OAuth, JWT, chaves de API, negociação de conteúdo.
• Corpo do pedido: qualquer string — JSON, XML, form-encoded, plain text. Enviado em POST/PUT/PATCH/DELETE.
• Basic auth: utilizador e palavra-passe, se o endpoint estiver protegido dessa forma.
• Códigos de estado esperados: lista ou intervalo. Por defeito 200-399, mas pode restringir a um código (ex. exatamente 201 para endpoint de criação) ou permitir específicos (ex. 200,202,204).

A verificação segue até um máximo de 5 redirecionamentos, descodifica gzip, analisa o Content-Type para detetar JSON. Cada verificação regista o código real, tempo de resposta, tamanho e eventuais erros. Múltiplas falhas consecutivas (configurável, por defeito 2) desencadeiam um incidente.

Asserções JSON path

Só os códigos de estado não chegam para muitas APIs. O endpoint health pode devolver 200 com body {"status": "degraded", "db": "down"} — ainda 200, mas é vital saber isto. Uma API de preços pode devolver 200 com body onde data.price caiu para null. Uma API de pesquisa pode devolver 200 com results: [], porque o índice caiu.

Para estes casos, configure uma asserção JSON path. Defina o caminho (ex. data.status ou health.checks.db) e o valor esperado (ex. healthy, true ou um número específico). Em cada verificação, a resposta é descodificada do JSON e o valor sob o caminho comparado. A não correspondência falha a verificação, independentemente do estado HTTP.

A sintaxe do caminho é notação de pontos com colchetes: data.items[0].id funciona, tal como users.john.email. O valor da asserção é comparado como string, por isso "true" corresponde a bool true, e números correspondem tanto como strings como números.

Padrões de autenticação

Os dois estilos de autenticação mais comuns funcionam out of the box. Para tokens Bearer (OAuth, JWT, chaves de API) use o campo headers: {"Authorization": "Bearer eyJhbGciOi..."}. O token fica na configuração do monitor e é enviado em cada verificação. Para basic auth use os campos dedicados de utilizador/palavra-passe — são armazenados e combinados num cabeçalho standard.

Se a autenticação requer assinatura por pedido ou refresh do token, é mais complicado. Dois padrões razoáveis: (1) configure um token de conta de serviço de longa duração especificamente para monitoramento, ou (2) exponha um endpoint health não autenticado que reflicta o estado do verdadeiro endpoint protegido, e monitorize esse. A maioria das APIs modernas já tem isto de origem.

Padrões recomendados

• Um monitor por endpoint crítico. Não teste todos — escolha 5-10 cuja falha causaria verdadeiro impacto.
• Use códigos exatos. O 200-399 por defeito é demasiado permissivo para APIs. Endpoint de criação deve devolver exatamente 201; idempotente exatamente 200; endpoint de login exatamente 200 (sucesso) ou 401 (falha bem formada — não 500).
• Combine o estado com asserção JSON. Juntos detetam regressões na camada de transporte e de conteúdo. Só o estado não apanha erros de conteúdo; só a asserção JSON é frágil em redirecionamentos.
• Defina um limite de tempo de resposta. Degradação de API é um indicador antecipado de problemas de dependências. Um monitor com rt_threshold_ms = 800 diz-lhe que a API está a abrandar antes de cair.
• Mantenha o corpo pequeno. A verificação é feita a cada minuto — corpos grandes desperdiçam largura de banda de ambos os lados. Payloads representativos mas mínimos chegam.

Combine com outros tipos de monitores

Para cada endpoint de API, o monitor de API verifica se o call funciona. Um monitor ping ou de porta à parte verifica se o host está ativo. Uma verificação de SSL/domínio sobre o mesmo host apanha problemas de certificado e registo. Um sub-monitor DNS vigia alterações de registos que possam indicar substituição. Quatro monitores juntos dão um retrato completo da API com mínimo sobreposição.

Configuração

Abra a ferramenta, clique em "Adicionar monitor", escolha o tipo "API". Cole o URL. Abra a secção Avançado. Selecione o método, cole os cabeçalhos como JSON, cole o corpo se necessário, defina basic auth se usar, insira os códigos esperados (ex. 200 ou 200,201). Adicione uma asserção JSON path se aplicável. Defina o intervalo e o limiar de confirmação. Guarde. A partir do próximo ciclo, o monitor chama a sua API exatamente como faria um integrador, valida a resposta e alerta em caso de regressão.

Perguntas frequentes

• Que métodos HTTP posso usar para monitorizar uma API?

  GET, POST, PUT, DELETE, PATCH e HEAD. Configure o método por monitor — para endpoints de escrita (POST/PUT/PATCH) o corpo do pedido também é configurável como string JSON ou form data.

• Como funcionam as asserções JSON?

  Indica o caminho JSON (ex. data.status ou results[0].id) e o valor esperado. O monitor obtém a resposta, analisa como JSON, extrai o caminho e compara com o esperado. Se não corresponder, a verificação falha com erro "assertion failed" mostrando o valor real.

• Posso enviar cabeçalhos de autenticação?

  Sim. Cabeçalhos HTTP personalizados são configuráveis por monitor — tokens Authorization, chaves de API, content-type, o que precisar. Os valores dos cabeçalhos são cifrados em repouso na base de dados. Para Basic Auth há um campo específico de username/password que assina automaticamente o pedido.

• E se a minha API devolver 200 com um payload de erro?

  Padrão comum: a API devolve HTTP 200 mas o corpo diz {"status":"error"}. Um monitor de uptime ingénuo pensa que está tudo bem. Use a asserção JSON status == "ok" para detetar isto — a asserção falha e o monitor reporta DOWN mesmo que o HTTP seja 200.

• Como lidar com uma API com rate limit?

  Defina o intervalo dos checks para respeitar o limite da API (ex. intervalo de 5 minutos se a API permitir 12 chamadas/hora). O monitor conta como uma chamada API por check de uma região. Checks multi-região multiplicam o número de chamadas — use single-region se a sua API tiver limites rigorosos.