Local REST API — passo a passo

Quando usar a API

A API local roda dentro do app desktop do NoSqlStudio numa porta configurável (default 8081, só loopback). Tooling externo pode chamar os mesmos engines que você usa pela UI:

• Pipeline CI/CD mascara dados de produção antes de refresh dev/staging (DataMask).
• PR gate: rode schema diff e bloqueie o merge quando aparecerem breaking changes (DB Compare).
• Datadog ou Grafana scrapeiam métricas de slow-query a cada 60s (Profiler).
• Cron job gera o relatório trimestral de compliance ANPD/GDPR (Compliance Reports).
• Slack bot dispara DB Copy + Slack thread + JIRA ticket em 5 minutos (workflow cross-tool).

Setup (única vez)

1. Abra o app desktop do NoSqlStudio, depois Settings → API Access.
2. Ative "Enable local API server" ON. O servidor inicia em 127.0.0.1:8081 por default.
3. Clique em "Create token" — dê um label (ex.: "CI/CD GitHub Actions"). O token raw aparece UMA VEZ — copie-o agora para 1Password / Vault / AWS Secrets Manager. Não pode ser recuperado depois.
4. (Opcional) Mude Bind para 0.0.0.0 se você precisa de acesso cross-host numa rede confiável. O Bearer token é a única proteção.

Primeiro request

Teste o endpoint health com curl em qualquer terminal:

curl -H "Authorization: Bearer nsk_..." \
  http://localhost:8081/api/health

Resposta esperada:

{
  "status": "ok",
  "app": "NoSqlStudio",
  "time": "2026-05-25T18:42:11.123Z",
  "uptimeSec": 327
}

Referência de endpoints (v1)

10 endpoints em 6 grupos de recurso. Spec OpenAPI 3.1 completo disponível em /api/openapi.json.

Autenticação

Todo endpoint autenticado requer um Bearer token no header Authorization. Tokens são strings hex aleatórias de 32-bytes com prefixo nsk_. Persistimos somente o SHA-256 do token raw em disco; um arquivo de tokens roubado é inútil sem os valores raw.

Escopos

• * — Acesso completo (default quando você cria um token sem especificar scopes).
• datamask — Jobs DataMask (create, status, abort).
• db-compare — Diff de schema + index do DB Compare.
• profiler — Feed de slow-query do Profiler.
• schema — Sampler de schema.
• cosmos — RU budget Cosmos + forecast.
• connections — Listar connections salvas (só metadados).

5 casos de uso reais

1. Mascarar dados de produção num pipeline GitHub Actions

Refresh dev/staging em schedule. Antes da cópia rodar, dispare DataMask via API e faça o pipeline falhar se o job der erro:

# .github/workflows/refresh-dev-db.yml
- name: Mask production data
  run: |
    curl -X POST http://nosql-jumpbox:8081/api/datamask/jobs \
      -H "Authorization: Bearer ${{ secrets.NOSQL_TOKEN }}" \
      -d '{"source":"mongodb://prod/...","target":"mongodb://dev/...","policy":"lgpd-prod"}'

2. Schema diff como PR gate

Bloqueie merge quando o PR introduz breaking changes no schema:

DIFF=$(curl http://localhost:8081/api/db-compare \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  -d '{"source":"main","target":"this-pr"}')
echo "$DIFF" | jq '.diff.breakingChanges | length' | xargs test 0 -eq

3. Feed de slow-query no Datadog / Grafana

Métrica customizada scrapeada a cada 60 segundos — conte queries acima do threshold p99 para o dashboard mostrar degradação ao vivo:

# Datadog custom metric scrape (every 60s)
curl "http://localhost:8081/api/profiler/slow-queries?since=5m&p99_ms_gte=500" \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  | jq '.queries | length'

4. Relatório trimestral de compliance ANPD/GDPR

Cron job gera o relatório e deposita o PDF no drive compartilhado de auditoria — DPO só assina:

# /etc/cron.d/quarterly-ropa
0 8 1 */3 * curl -X POST http://localhost:8081/api/compliance/reports/quarterly \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  -o /audit/$(date +%Y-Q%q).pdf

5. Slack bot → DataMask → ticket JIRA

Dev pede cópia de produção mascarada no Slack, bot dispara DB Copy + Mask, posta status no thread, abre ticket JIRA com link de download — 5 minutos end-to-end:

# Slack bolt handler
app.command('/db-copy', async ({ command, ack, say }) => {
  await ack();
  const job = await fetch('http://localhost:8081/api/db-copy/jobs', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${process.env.NOSQL_TOKEN}` },
    body: JSON.stringify({ source: command.text, target: 'dev-sandbox' })
  }).then(r => r.json());
  await say(`📋 Job ${job.jobId} queued`);
});

Códigos de status HTTP

Checklist de segurança

• Faça bind em 127.0.0.1 a menos que precise de acesso cross-host. 0.0.0.0 expõe a API em toda NIC — rotação de token vira crítica.
• Rotacione tokens a cada 90 dias. Revogue imediatamente quando um colaborador sai ou quando um token vaza (ex.: acidentalmente commitado em repo público).
• Use tokens por ambiente (um para CI, um para scrape do Datadog, um para Slack bot) com o scope mínimo que cada um precisa.
• Cada request autenticado é registrado no log de auditoria consolidado (Tools → Audit Log). Cross-reference token id + source IP se você suspeita de abuso.
• TLS NÃO é auto-configurado — use um reverse proxy (nginx, Caddy) na frente da API se você fizer bind em 0.0.0.0.

Spec OpenAPI

Baixe o spec OpenAPI 3.1 completo e importe no Postman, Insomnia, ou Bruno para explorar cada endpoint interativamente:

curl http://localhost:8081/api/openapi.json -o nosqlstudio-api.json
# Import into Postman / Insomnia / Bruno