100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# Usage: API Examples
|
|
|
|
## Projection Query via Gateway (HTTP → gRPC)
|
|
```bash
|
|
curl -sS -X POST \
|
|
-H "x-tenant-id: tenant-a" \
|
|
-H "x-correlation-id: demo" \
|
|
-H "traceparent: 00-00000000000000000000000000000001-0000000000000001-01" \
|
|
http://localhost:8080/v1/query/User \
|
|
-d '{"uqf":"{\"eq\":{\"id\":\"u1\"}}"}'
|
|
```
|
|
|
|
## Projection Query via gRPC (direct, internal)
|
|
```bash
|
|
grpcurl -d '{"tenant_id":"tenant-a","view_type":"User","uqf":"{}"}' \
|
|
-H 'x-tenant-id: tenant-a' \
|
|
-H 'x-correlation-id: demo' \
|
|
-H 'traceparent: 00-00000000000000000000000000000001-0000000000000001-01' \
|
|
-plaintext localhost:9090 projection.gateway.v1.QueryService/ExecuteQuery
|
|
```
|
|
|
|
## Aggregate Command via Gateway (HTTP → gRPC)
|
|
```bash
|
|
curl -sS -X POST \
|
|
-H "x-tenant-id: tenant-a" \
|
|
-H "x-correlation-id: demo" \
|
|
-H "traceparent: 00-00000000000000000000000000000001-0000000000000001-01" \
|
|
http://localhost:8080/v1/aggregate/BankAccount/command \
|
|
-d '{"id":"acc-1","command_type":"Open","payload":{"owner":"Alice"}}'
|
|
```
|
|
|
|
## Runner Admin via Gateway (HTTP → gRPC)
|
|
```bash
|
|
curl -sS -X POST \
|
|
-H "x-tenant-id: tenant-a" \
|
|
-H "authorization: Bearer <token>" \
|
|
http://localhost:8080/admin/runner/drain?wait_ms=0
|
|
```
|
|
|
|
## Document Storage via Control API (S3-backed)
|
|
List documents for a tenant (Control API uses UUID tenant ids):
|
|
```bash
|
|
curl -sS \
|
|
-H "authorization: Bearer <token>" \
|
|
-H "x-tenant-id: <tenant-uuid>" \
|
|
"http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs"
|
|
```
|
|
|
|
Upload a document (stores at `docs/<tenant>/<type>/<id>/<filename>`):
|
|
```bash
|
|
curl -sS -X PUT \
|
|
-H "authorization: Bearer <token>" \
|
|
-H "x-tenant-id: <tenant-uuid>" \
|
|
-H "content-type: application/octet-stream" \
|
|
--data-binary @./bundle.tar.gz \
|
|
"http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/deployments/<doc-id>/bundle.tar.gz"
|
|
```
|
|
|
|
Download by object key (streamed proxy; key must belong to the tenant prefix):
|
|
```bash
|
|
curl -sS -o ./out.tar.gz \
|
|
-H "authorization: Bearer <token>" \
|
|
-H "x-tenant-id: <tenant-uuid>" \
|
|
"http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/object/<url-encoded-key>"
|
|
```
|
|
|
|
Delete by object key (requires `control:write`):
|
|
```bash
|
|
curl -sS -X DELETE \
|
|
-H "authorization: Bearer <token>" \
|
|
-H "x-tenant-id: <tenant-uuid>" \
|
|
"http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/object/<url-encoded-key>"
|
|
```
|
|
|
|
Presign upload (JSON body; returns `PUT` URL and `key`):
|
|
```bash
|
|
curl -sS -X POST \
|
|
-H "authorization: Bearer <token>" \
|
|
-H "content-type: application/json" \
|
|
-H "x-tenant-id: <tenant-uuid>" \
|
|
-d '{"doc_type":"deployments","doc_id":"<doc-id>","filename":"bundle.tar.gz","content_type":"application/gzip"}' \
|
|
"http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/presign/upload"
|
|
```
|
|
|
|
Presign download (JSON body with full `key` under that tenant):
|
|
```bash
|
|
curl -sS -X POST \
|
|
-H "authorization: Bearer <token>" \
|
|
-H "content-type: application/json" \
|
|
-H "x-tenant-id: <tenant-uuid>" \
|
|
-d '{"key":"docs/<tenant-uuid>/deployments/<doc-id>/bundle.tar.gz"}' \
|
|
"http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/presign/download"
|
|
```
|
|
|
|
Environment variables for the Control API (also accept `S3_*` names without the `CONTROL_` prefix; see `S3_PLAN.md`):
|
|
- `CONTROL_S3_ENDPOINT` — S3 API base URL used by the server client
|
|
- `CONTROL_S3_PUBLIC_ENDPOINT` — optional; host used in presigned URLs when browsers must reach a different host than the API (e.g. `localhost:9000` vs `minio:9000` in compose)
|
|
- `CONTROL_S3_REGION`, `CONTROL_S3_BUCKET_DOCS`, `CONTROL_S3_PREFIX_DOCS`, `CONTROL_S3_FORCE_PATH_STYLE`, `CONTROL_S3_INSECURE`
|
|
- Secrets may be mounted as files: `CONTROL_S3_ACCESS_KEY_ID_FILE`, `CONTROL_S3_SECRET_ACCESS_KEY_FILE`
|