Pular para conteúdo

API REST

A API (FastAPI) é a mesma usada pela interface: tudo o que a GUI faz pode ser automatizado.

Recurso Onde
Swagger UI https://<servidor>/api/docs
ReDoc https://<servidor>/api/redoc
OpenAPI (JSON) https://<servidor>/api/openapi.json e docs/api/openapi.json no repositório
Tabela de endpoints Endpoints da API (gerada do OpenAPI, com a permissão de cada endpoint)

Prefixo: /api/v1, exceto /api/health e /metrics.

Autenticação

Crie em Perfil › Tokens de API (ou POST /api/v1/auth/tokens). O token herda as permissões do usuário.

curl -s -H "Authorization: Bearer qv_xxxxxxxx" https://quantix.empresa.local/api/v1/overview
curl -s -X POST https://quantix.empresa.local/api/v1/auth/login \
     -H 'Content-Type: application/json' -d '{"username":"admin","password":"..."}'
# {"access_token":"eyJ...","refresh_token":"eyJ...","token_type":"bearer","expires_in":1800,"must_change_password":false}
curl -s -H "Authorization: Bearer eyJ..." https://quantix.empresa.local/api/v1/auth/me
curl -s -X POST https://quantix.empresa.local/api/v1/auth/refresh -H 'Content-Type: application/json' \
     -d '{"refresh_token":"eyJ..."}'

directory_id opcional no login força um diretório específico.

Endpoints /api/v1/collector/* e /api/v1/ingest/* usam X-Collector-Token: qvc_.... Uso interno dos coletores.

Convenções

Tema Convenção
Formato JSON UTF-8. Datas em ISO-8601 com fuso (UTC). IDs são UUID
Paginação ?offset=0&limit=100. Resposta {"items": [...], "total": N, "offset": 0, "limit": 100} em /entities, /devices, /findings, /changes, /admin/users, /admin/audit, /automation/jobs. Cada endpoint tem um limit máximo (ex.: 1000 em /findings, 5000 em /entities)
Filtros múltiplos valores separados por vírgula: ?type=volume,pool, ?severity=critical,warning, ?status=open,acknowledged
Tempo em métricas start/end em ISO-8601, now ou relativo -15m, -24h, -7d, -4w
Segredos nunca retornados. Respostas indicam secret_fields_set, secrets_set, bind_password_set ou is_set
Escopo de tenant aplicado automaticamente conforme os papéis do usuário (ressalvas)
Auditoria alterações são registradas com usuário e IP

Erros

HTTP Quando Corpo
400 regra de negócio ou ValueError (ex.: “início deve ser anterior ao fim”, “papéis padrão não podem ser alterados”) {"detail": "mensagem"}
401 sem autenticação, token inválido/expirado {"detail": "autenticação necessária"} (+ WWW-Authenticate: Bearer)
403 sem a permissão {"detail": "permissão necessária: <descrição>"}
404 objeto inexistente ou fora do escopo de tenant {"detail": "… não encontrado"}
409 conflito (nome duplicado, credencial em uso, coletor com dispositivos) {"detail": "…"}
422 validação do corpo (pydantic) ou variáveis fora da faixa {"detail": [...]} ou {"detail": {"message": "valores inválidos", "errors": {"chave": "motivo"}}}
423 conta bloqueada {"detail": "usuário temporariamente bloqueado…"}
502 falha no provedor de IA {"detail": "falha ao consultar o provedor de IA: …"}

Exemplo: consulta de métricas

curl -s -X POST https://quantix.empresa.local/api/v1/metrics/query \
  -H "Authorization: Bearer $QV_TOKEN" -H 'Content-Type: application/json' -d '{
    "entity_type": "volume", "metric": "lat_ms", "mode": "topn",
    "agg": "p95", "start": "-24h", "end": "now", "limit": 10, "order": "desc"
  }'
Campo Valores
entity_type, metric do catálogo (validados)
mode timeseries (padrão), topn, latest, stat, heatmap, distribution
agg avg, max, min, p95, sum, last (padrão: o do catálogo)
entity_ids lista opcional de UUIDs. Sem ela, timeseries/heatmap usam os top-N
limit (1–500), order (desc/asc), step (60 s–7 dias), buckets (5–100, distribuição) —
with_names inclui names (id → nome, tipo, dispositivo) na resposta (padrão true)

A resposta informa a tabela usada (metrics, metrics_1h ou metrics_1d), o passo, a unidade e a agregação.

Exemplo: automação de cadastro

# credencial
CID=$(curl -s -X POST $URL/api/v1/credentials -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name":"svc-pure","kind":"token","token":"T-123"}' | jq -r .id)
# dispositivo
curl -s -X POST $URL/api/v1/devices -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"name\":\"PURE-DC1-01\",\"plugin\":\"pure_flasharray\",\"addresses\":[\"10.0.0.10\"],\"credential_id\":\"$CID\"}"