Local REST API — step-by-step

API का उपयोग कब करें

Local API NoSqlStudio desktop ऐप के अंदर एक configurable port पर चलती है (default 8081, केवल loopback)। External tooling उन्हीं engines को call कर सकता है जिनका आप UI के माध्यम से उपयोग करते हैं:

• CI/CD pipeline dev/staging refresh करने से पहले production data को mask करता है (DataMask)।
• PR gate: schema diff चलाएँ और breaking changes दिखने पर merge block करें (DB Compare)।
• Datadog या Grafana हर 60s slow-query metrics scrape करते हैं (Profiler)।
• Cron job त्रैमासिक ANPD/GDPR compliance रिपोर्ट उत्पन्न करता है (Compliance Reports)।
• Slack bot 5 मिनटों में DB Copy + Slack thread + JIRA ticket fire करता है (cross-tool workflow)।

Setup (एक बार)

1. NoSqlStudio desktop ऐप खोलें, फिर Settings → API Access।
2. "Enable local API server" को ON toggle करें। Server डिफ़ॉल्ट रूप से 127.0.0.1:8081 पर शुरू होता है।
3. "Create token" पर क्लिक करें — एक label दें (जैसे "CI/CD GitHub Actions")। Raw token एक बार दिखता है — अभी इसे 1Password / Vault / AWS Secrets Manager में कॉपी करें। बाद में retrieve नहीं किया जा सकता।
4. (वैकल्पिक) यदि आपको trusted network पर cross-host access चाहिए तो Bind को 0.0.0.0 में बदलें। Bearer token एकमात्र protection है।

पहला request

किसी भी terminal से curl के साथ health endpoint test करें:

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

अपेक्षित response:

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

Endpoint reference (v1)

6 resource groups में 10 endpoints। पूर्ण OpenAPI 3.1 spec /api/openapi.json पर उपलब्ध।

प्रमाणीकरण

हर authenticated endpoint को Authorization header में एक Bearer token चाहिए। Tokens 32-byte random hex strings हैं जिनका prefix nsk_ है। हम disk पर केवल raw token का SHA-256 persist करते हैं; raw values के बिना चुराई गई tokens file बेकार है।

Scopes

• * — पूर्ण पहुँच (default जब आप बिना scopes specify किए token बनाते हैं)।
• datamask — DataMask jobs (create, status, abort)।
• db-compare — DB Compare schema + index diff।
• profiler — Profiler slow-query feed।
• schema — Schema sampler।
• cosmos — Cosmos RU budget + forecast।
• connections — सहेजे गए connections की सूची (केवल metadata)।

5 वास्तविक उपयोग के मामले

1. GitHub Actions pipeline में production data mask करें

Schedule पर dev/staging refresh। Copy चलने से पहले, API के माध्यम से DataMask fire करें और job error देने पर pipeline को fail करें:

# .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. PR gate के रूप में Schema diff

जब PR schema में breaking changes लाता है तो merge block करें:

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. Datadog / Grafana में Slow-query feed

हर 60 सेकंड scrape की गई custom metric — p99 threshold से ऊपर queries गिनें ताकि dashboard live degradation दिखाए:

# 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. त्रैमासिक ANPD/GDPR compliance रिपोर्ट

Cron job रिपोर्ट उत्पन्न करता है और PDF को shared audit drive पर drop करता है — DPO केवल हस्ताक्षर करता है:

# /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 → JIRA ticket

Dev Slack में masked production copy माँगता है, bot DB Copy + Mask fire करता है, thread पर status post करता है, download link के साथ JIRA ticket खोलता है — 5 मिनट 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`);
});

HTTP status codes

Security checklist

• 127.0.0.1 पर bind करें जब तक आपको cross-host access की आवश्यकता न हो। 0.0.0.0 हर NIC पर API expose करता है — token rotation critical हो जाता है।
• हर 90 दिनों में tokens rotate करें। जब कोई कर्मचारी छोड़ता है या जब token leak होता है (जैसे गलती से public repo में commit) तुरंत revoke करें।
• हर environment के लिए per-token उपयोग करें (एक CI के लिए, एक Datadog scrape के लिए, एक Slack bot के लिए) हर एक को आवश्यक न्यूनतम scope के साथ।
• हर authenticated request consolidated audit log में रिकॉर्ड होता है (Tools → Audit Log)। यदि आपको दुरुपयोग का संदेह है तो token id + source IP को cross-reference करें।
• TLS auto-configured नहीं है — यदि आप 0.0.0.0 पर bind करते हैं तो API के सामने एक reverse proxy (nginx, Caddy) उपयोग करें।

OpenAPI spec

पूर्ण OpenAPI 3.1 spec डाउनलोड करें और हर endpoint को interactively explore करने के लिए Postman, Insomnia, या Bruno में import करें:

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