API REST

O Console Web do NGBackup expõe uma API REST versionada em /api/v1/. Tudo o que a interface do console faz — executar jobs, navegar pontos de restauração, ler a saúde do ambiente — está disponível para clientes de máquina pelos mesmos endpoints.

O documento OpenAPI

A API descreve a si mesma. Busque o documento OpenAPI 3.1 gerado em um Console Web em execução (autenticado, como todo endpoint):

curl -H "Authorization: Bearer $NGB_TOKEN" \
  https://console.example.com/api/v1/openapi.json

O documento é gerado a partir das anotações dos próprios handlers do servidor em tempo de compilação, portanto não pode divergir das rotas que descreve. Cobertura atual: tokens, auth, operations, restore, directors, storage-media, stats. Grupos ainda internos (pipeline de configuração, admin, plugins, relatórios, automação, advanced) são adicionados conforme estabilizam — trate qualquer endpoint ausente do documento como sujeito a mudança sem aviso.

Autenticação: tokens de API pessoais

Usuários interativos entram com cookie de sessão; clientes de máquina usam tokens de API pessoais — credenciais bearer com o papel do usuário emissor congelado no momento da criação.

Crie um pela interface (Segurança → Tokens de API) ou pela API usando uma sessão de navegador:

# Retorna o resumo do token mais "plaintext" — exibido UMA única vez.
curl -X POST https://console.example.com/api/v1/tokens \
  -H "Cookie: backupweb_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "terraform-prod"}'

Guarde o valor plaintext (ngbt_…) — o servidor guarda apenas o SHA-256. Depois autentique qualquer requisição com ele:

curl -H "Authorization: Bearer ngbt_…" \
  https://console.example.com/api/v1/operations/jobs

Tokens agem com o papel sob o qual foram criados (admin, operator, readonly ou um papel de capacidades customizado). Revogue a qualquer momento — a revogação é imediata e a linha permanece como trilha de auditoria:

curl -X DELETE -H "Authorization: Bearer ngbt_…" \
  https://console.example.com/api/v1/tokens/<id>

Criação e revogação são auditadas (api_token.create / api_token.revoke).

Tour rápido

AUTH='Authorization: Bearer ngbt_…'
BASE=https://console.example.com/api/v1

# Saúde consolidada do Director
curl -H "$AUTH" $BASE/director/health

# Jobs recentes
curl -H "$AUTH" $BASE/operations/jobs/recent

# Executar um job
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"job": "BackupWebServer", "level": "Incremental"}' \
  $BASE/operations/jobs/run

# Buscar um arquivo no catálogo em toda a cadeia de restauração
curl -H "$AUTH" "$BASE/restore/bvfs/search?jobids=101,102&q=config.ini"

Os esquemas de requisição e resposta de cada endpoint coberto, incluindo códigos de status e tipos de parâmetros, estão no documento OpenAPI acima — aponte qualquer cliente compatível com OpenAPI (Swagger UI, Postman, openapi-generator) para ele.

Eventos de alerta para integrações

Canais de notificação (e-mail/webhook, Administração → Notificações) assinam padrões de eventos. Ações relevantes para máquinas incluem:

Ação	Dispara quando
job.completed.error / job.completed.warning	um job termina mal
client.silence.warn / client.silence.crit	um cliente ficou sem backup bem-sucedido por mais tempo que o limiar warn/crit
client.silence.ok	um cliente antes silencioso se recupera
api_token.create / api_token.revoke	ciclo de vida de tokens (auditoria)

Os limiares são configuráveis pelo operador (Administração → Monitoramento); canais webhook podem apontar para URLs de ingestão no estilo PagerDuty/OpsGenie.