API Protocols, Auth, and Conventions
Last validated: 2026-05-11
Use this page before invoking any API method. It defines transport behavior, authentication, headers, and response conventions used throughout VBase.
Transport and Exposure Model
- Runtime is gRPC-first (
tonicservice implementation). - HTTP routes in proto are gateway annotations intended for gRPC transcoding.
- Service package is
dodil.vbase.v1. - In deployments without HTTP transcoding enabled, use gRPC directly.
Common Environment Variables
export VBASE_GRPC="rpc.dev.dodil.io:443"
export VBASE_HTTP="api.dev.dodil.io:443"
export TOKEN="<bearer_token>"
export ORG_ID="<organization_id>"Typical values are environment-specific. Keep gRPC and HTTP endpoints separate because some environments expose only one protocol surface.
Auth and Metadata Headers
| Header | Used by | Required | Purpose |
|---|---|---|---|
authorization: Bearer <token> | gRPC + HTTP | Yes | Authenticates principal and scopes. |
dbname: <db_name> | gRPC RunCommand and Milvus passthrough paths | Often | Sets tenant DB context for methods that require DB scoping. |
db_name: <db_name> | gRPC RunCommand metadata fallback | Optional | Alternate metadata key accepted by runtime. |
x-org-name: <org_name> | Some client flows | Optional | Forwarded by CLI in some code paths; not required for all APIs. |
Response Envelope Pattern
Most responses include:
- Domain payload field(s) such as
database,cluster,services,job,policy. response(common.MsgResp) for success/code/message.
MsgResp fields:
success(bool)code(optional string)message(optional string)
Service Status Model
ServiceStatus values used by service APIs:
CREATINGRUNNINGUPDATINGDELETINGDELETEDERRORSTOPPINGSTOPPEDUPDATE_FAILEDUNKNOWNRESIZING
Pagination and Filtering Notes
ListServicesRequest supports optional filtering and pagination:
status_filterpage_sizepageinclude_deleted
Server behavior notes:
status_filter = 0is treated as no filter because it is proto default.page_size = 0means server default page size.
Health Check Examples
Use health check to validate connectivity before calling state-changing APIs.
gRPC
grpcurl -insecure \
-H "authorization: Bearer $TOKEN" \
-d '{}' \
"rpc.dev.dodil.io:443" dodil.vbase.v1.VBaseService/HealthCheckHTTP
curl -sS \
-H "Authorization: Bearer $TOKEN" \
"https://api.dev.dodil.io:443/v1/vbase/healthz"Recommended Call Strategy
- Use CLI (
dodil vbase) for common shared-database workflows. - Use direct gRPC for dedicated cluster lifecycle and advanced methods.
- Use HTTP gateway only when your environment explicitly enables transcoding and the annotated route has no drift issue.