droboticflow-new/docs/external-business-db-write-api-integration.md
eust-w 43326d6a5e feat(platform): land workflow, data tooling, and docs updates
Include the accumulated workflow scheduling, run history, subtree rerun, operator UI, deployment, data asset, object storage, database browser, and documentation changes currently in the worktree.
2026-04-24 12:29:46 +08:00

4.6 KiB

External Business DB Write API Integration Guide

This document is the handoff guide for internal teams and third-party integrators who need to write data into a preconfigured business MongoDB connection through Drobodata.

1. Integration Target

  • Base URL: http://114.111.24.223:30080
  • Auth header: X-API-Key
  • Allowed connectionId: mongo-6fc71b9f604165b38279f068c4294423
  • Allowed collection whitelist:
    • businessWriteValidation

Current API key:

dbw_<rotate-and-send-out-of-band>

Do not keep the live plaintext key in git, wiki pages, or chat history. Distribute it out of band to the third party.

If this key is rotated later, the old key immediately becomes invalid.

2. Supported Operations

Third parties can call these routes:

  • POST /api/external/business-db/documents
  • PATCH /api/external/business-db/documents/:documentId
  • POST /api/external/business-db/upserts

All requests must include:

Content-Type: application/json
X-API-Key: dbw_...

3. Request Rules

  • connectionId must be the authorized one
  • collection must be in the token whitelist
  • document, patch, match, and setOnInsert must be plain JSON objects
  • Mongo update operators such as $set, $inc, $push are not accepted

4. Create Document

Request:

curl -X POST 'http://114.111.24.223:30080/api/external/business-db/documents' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dbw_<your-live-api-key>' \
  --data '{
    "connectionId": "mongo-6fc71b9f604165b38279f068c4294423",
    "collection": "businessWriteValidation",
    "document": {
      "runLabel": "partner-demo-001",
      "source": "partner-a",
      "value": 123,
      "createdAt": "2026-04-14T17:20:00+08:00"
    }
  }'

Typical success response:

{
  "connectionId": "mongo-6fc71b9f604165b38279f068c4294423",
  "collection": "businessWriteValidation",
  "operation": "created",
  "document": {
    "_id": {
      "$oid": "69de3ab85edc4783ca5ce18b"
    },
    "runLabel": "partner-demo-001",
    "source": "partner-a",
    "value": 123,
    "createdAt": "2026-04-14T17:20:00+08:00"
  }
}

5. Patch Existing Document By _id

Request:

curl -X PATCH 'http://114.111.24.223:30080/api/external/business-db/documents/<documentId>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dbw_<your-live-api-key>' \
  --data '{
    "connectionId": "mongo-6fc71b9f604165b38279f068c4294423",
    "collection": "businessWriteValidation",
    "patch": {
      "value": 789,
      "status": "done"
    }
  }'

Typical success response:

{
  "connectionId": "mongo-6fc71b9f604165b38279f068c4294423",
  "collection": "businessWriteValidation",
  "operation": "updated",
  "document": {
    "_id": {
      "$oid": "69de3ab85edc4783ca5ce18b"
    },
    "runLabel": "partner-demo-001",
    "source": "partner-a",
    "value": 789,
    "status": "done"
  }
}

6. Upsert By Business Key

Use this when the third party wants "insert if not exists, otherwise update".

Request:

curl -X POST 'http://114.111.24.223:30080/api/external/business-db/upserts' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dbw_<your-live-api-key>' \
  --data '{
    "connectionId": "mongo-6fc71b9f604165b38279f068c4294423",
    "collection": "businessWriteValidation",
    "match": {
      "runLabel": "partner-demo-001"
    },
    "patch": {
      "source": "partner-a",
      "value": 456,
      "updatedAt": "2026-04-14T17:21:00+08:00"
    },
    "setOnInsert": {
      "createdBy": "partner-a"
    }
  }'

Typical success response:

  • Insert path: operation is created
  • Update path: operation is updated

7. Error Cases

Common failures:

  • 401 Unauthorized
    • Missing X-API-Key
    • Invalid API key
    • Rotated or disabled API key
  • 403 Forbidden
    • connectionId not allowed for this token
    • collection not allowed for this token
  • 400 Bad Request
    • Invalid JSON
    • Missing required fields
    • document / patch / match not plain JSON objects

8. Verified Live Test On April 14, 2026

This configuration was tested against the live remote Kubernetes deployment on April 14, 2026.

Verified successfully:

  • create document
  • upsert document
  • patch document by _id

Test collection:

  • businessWriteValidation

Sample live test markers:

  • external-api-test-202604141712
  • external-api-upsert-202604141712

9. Operational Notes

  • This API does not expose raw MongoDB credentials to third parties
  • A token should be scoped to the smallest possible set of collections
  • If a third party no longer needs access, disable or delete the token
  • If a key is leaked, rotate it immediately