Local REST API — paso a paso

Cuándo usar la API

La API local corre dentro del app desktop del NoSqlStudio en un puerto configurable (default 8081, solo loopback). Tooling externo puede llamar los mismos engines que usa por la UI:

• Pipeline CI/CD enmascara datos de producción antes de refresh dev/staging (DataMask).
• PR gate: corra schema diff y bloquee el merge cuando aparezcan breaking changes (DB Compare).
• Datadog o Grafana scrapean métricas de slow-query cada 60s (Profiler).
• Cron job genera el reporte trimestral de compliance ANPD/GDPR (Compliance Reports).
• Slack bot dispara DB Copy + Slack thread + JIRA ticket en 5 minutos (workflow cross-tool).

Setup (una sola vez)

1. Abra el app desktop del NoSqlStudio, luego Settings → API Access.
2. Active "Enable local API server" ON. El servidor inicia en 127.0.0.1:8081 por default.
3. Haga clic en "Create token" — dé un label (ej.: "CI/CD GitHub Actions"). El token raw aparece UNA VEZ — cópielo ahora a 1Password / Vault / AWS Secrets Manager. No puede ser recuperado después.
4. (Opcional) Cambie Bind a 0.0.0.0 si necesita acceso cross-host en una red confiable. El Bearer token es la única protección.

Primer request

Pruebe el endpoint health con curl en cualquier terminal:

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

Respuesta esperada:

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

Referencia de endpoints (v1)

10 endpoints en 6 grupos de recurso. Spec OpenAPI 3.1 completo disponible en /api/openapi.json.

Autenticación

Cada endpoint autenticado requiere un Bearer token en el header Authorization. Tokens son strings hex aleatorias de 32-bytes con prefijo nsk_. Persistimos solamente el SHA-256 del token raw en disco; un archivo de tokens robado es inútil sin los valores raw.

Scopes

• * — Acceso completo (default cuando crea un token sin especificar scopes).
• datamask — Jobs DataMask (create, status, abort).
• db-compare — Diff de schema + index del DB Compare.
• profiler — Feed de slow-query del Profiler.
• schema — Sampler de schema.
• cosmos — RU budget Cosmos + forecast.
• connections — Listar connections guardadas (solo metadatos).

5 casos de uso reales

1. Enmascarar datos de producción en un pipeline GitHub Actions

Refresh dev/staging en schedule. Antes que la copia corra, dispare DataMask vía API y haga el pipeline fallar si el job da error:

# .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

Bloquee merge cuando el PR introduce breaking changes en el 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 en Datadog / Grafana

Métrica customizada scrapeada cada 60 segundos — cuente queries arriba del threshold p99 para que el dashboard muestre degradación en 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. Reporte trimestral de compliance ANPD/GDPR

Cron job genera el reporte y deposita el PDF en el drive compartido de auditoría — DPO solo firma:

# /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 pide copia de producción enmascarada en Slack, bot dispara DB Copy + Mask, postea status en el thread, abre ticket JIRA con link de descarga — 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 seguridad

• Haga bind en 127.0.0.1 a menos que necesite acceso cross-host. 0.0.0.0 expone la API en cada NIC — rotación de token se vuelve crítica.
• Rote tokens cada 90 días. Revoque inmediatamente cuando un empleado sale o cuando un token se filtra (ej.: accidentalmente commiteado a repo público).
• Use tokens por ambiente (uno para CI, uno para scrape de Datadog, uno para Slack bot) con el scope mínimo que cada uno necesita.
• Cada request autenticado se registra en el log de auditoría consolidado (Tools → Audit Log). Cross-reference token id + source IP si sospecha de abuso.
• TLS NO está auto-configurado — use un reverse proxy (nginx, Caddy) en frente de la API si hace bind en 0.0.0.0.

Spec OpenAPI

Descargue el spec OpenAPI 3.1 completo e importe en Postman, Insomnia, o Bruno para explorar cada endpoint interactivamente:

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