droboticflow/docs/external-business-db-write-api-integration.md
2026-06-16 17:56:50 +08:00

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