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 -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\"}"