forked from longtao.wu/droboticflow
194 lines
4.6 KiB
Markdown
194 lines
4.6 KiB
Markdown
# 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: `<drobodata-base-url>`
|
|
- Auth header: `X-API-Key`
|
|
- Allowed connectionId: `<authorized-mongo-connection-id>`
|
|
- Allowed collection whitelist:
|
|
- `businessWriteValidation`
|
|
|
|
Current API key:
|
|
|
|
```text
|
|
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. The platform stores only a hash and preview; the full key is shown only in the create or rotate response.
|
|
|
|
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:
|
|
|
|
```http
|
|
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:
|
|
|
|
```bash
|
|
curl -X POST '<drobodata-base-url>/api/external/business-db/documents' \
|
|
-H 'Content-Type: application/json' \
|
|
-H 'X-API-Key: dbw_<your-live-api-key>' \
|
|
--data '{
|
|
"connectionId": "<authorized-mongo-connection-id>",
|
|
"collection": "businessWriteValidation",
|
|
"document": {
|
|
"runLabel": "partner-demo-001",
|
|
"source": "partner-a",
|
|
"value": 123,
|
|
"createdAt": "2026-04-14T17:20:00+08:00"
|
|
}
|
|
}'
|
|
```
|
|
|
|
Typical success response:
|
|
|
|
```json
|
|
{
|
|
"connectionId": "<authorized-mongo-connection-id>",
|
|
"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:
|
|
|
|
```bash
|
|
curl -X PATCH '<drobodata-base-url>/api/external/business-db/documents/<documentId>' \
|
|
-H 'Content-Type: application/json' \
|
|
-H 'X-API-Key: dbw_<your-live-api-key>' \
|
|
--data '{
|
|
"connectionId": "<authorized-mongo-connection-id>",
|
|
"collection": "businessWriteValidation",
|
|
"patch": {
|
|
"value": 789,
|
|
"status": "done"
|
|
}
|
|
}'
|
|
```
|
|
|
|
Typical success response:
|
|
|
|
```json
|
|
{
|
|
"connectionId": "<authorized-mongo-connection-id>",
|
|
"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:
|
|
|
|
```bash
|
|
curl -X POST '<drobodata-base-url>/api/external/business-db/upserts' \
|
|
-H 'Content-Type: application/json' \
|
|
-H 'X-API-Key: dbw_<your-live-api-key>' \
|
|
--data '{
|
|
"connectionId": "<authorized-mongo-connection-id>",
|
|
"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
|