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.
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/documentsPATCH /api/external/business-db/documents/:documentIdPOST /api/external/business-db/upserts
All requests must include:
Content-Type: application/json
X-API-Key: dbw_...
3. Request Rules
connectionIdmust be the authorized onecollectionmust be in the token whitelistdocument,patch,match, andsetOnInsertmust be plain JSON objects- Mongo update operators such as
$set,$inc,$pushare 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:
operationiscreated - Update path:
operationisupdated
7. Error Cases
Common failures:
401 Unauthorized- Missing
X-API-Key - Invalid API key
- Rotated or disabled API key
- Missing
403 ForbiddenconnectionIdnot allowed for this tokencollectionnot allowed for this token
400 Bad Request- Invalid JSON
- Missing required fields
document/patch/matchnot 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-202604141712external-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