API Reference
The gateway is gRPC and gRPC-Web only; HTTP serves gRPC-Web and the health checks. See Calling the gateway.
Complete API documentation for the Virtufin API gateway.
Generated API Documentation
- C# SDK Reference — Auto-generated docs for
Virtufin.ApiandVirtufin.Api.Client - Python SDK Reference — Auto-generated docs for
virtufinpackage - TypeScript SDK Reference — Auto-generated docs for TypeScript client
Table of Contents
Health Check
GET /health
Returns the health status of the API gateway.
Response:
{
"status": "Healthy",
"totalDuration": "00:00:00.0100000",
"entries": {
"dapr": {
"status": "Healthy",
"description": "Dapr is available"
},
"grpc-channel-pool": {
"status": "Healthy",
"description": "gRPC channel pool is initialized"
}
}
}
gRPC Services
The Virtufin API exposes two main gRPC services defined in gateway.proto and config.proto.
Gateway Service (virtufin.Gateway)
| Method | Request | Response | Description |
|---|---|---|---|
Invoke |
InvokeRequest |
InvokeResponse |
Invoke a method on a service |
ListServices |
ListServicesRequest |
ListServicesResponse |
List all registered services |
ListMethods |
ListMethodsRequest |
ListMethodsResponse |
List methods for a service |
GetMethodSchema |
GetMethodSchemaRequest |
GetMethodSchemaResponse |
Describe a method's wire format |
State Service (virtufin.State)
| Method | Request | Response | Description |
|---|---|---|---|
SaveState |
SaveStateRequest |
SaveStateResponse |
Save state and publish event |
GetState |
GetStateRequest |
GetStateResponse |
Get a single state value |
DeleteState |
DeleteStateRequest |
DeleteStateResponse |
Delete state and publish event |
QueryState |
QueryStateRequest |
QueryStateResponse |
Search state entries via Dapr's query-state DSL (requires a Query-API-capable store; see QueryState) |
GetBulkState |
GetBulkStateRequest |
GetBulkStateResponse |
Get multiple state values by key |
DeleteBulkState |
DeleteBulkStateRequest |
DeleteBulkStateResponse |
Delete multiple state entries by key |
Config Service (virtufin.Config)
| Method | Request | Response | Description |
|---|---|---|---|
ListServices |
ListConfigServicesRequest |
ListConfigServicesResponse |
List all service configs |
GetService |
GetConfigServiceRequest |
GetConfigServiceResponse |
Get a specific service config |
Gateway Service Methods
Invoke
Invokes a method on a registered service.
Request (InvokeRequest):
message InvokeRequest {
string service = 1; // Service name (e.g., "workmanager")
string method = 2; // Method name (e.g., "GetWorker")
string request_data = 3; // JSON request payload
}
Response (InvokeResponse):
message InvokeResponse {
bool success = 1; // Whether the call succeeded
string status = 2; // gRPC status code
string message = 3; // Error message if failed
string response_data = 4; // JSON response payload
}
ListServices
Lists all services registered with the gateway.
Request: ListServicesRequest (empty)
Response:
message ListServicesResponse {
repeated string services = 1; // List of service names
}
ListMethods
Lists all methods available on a service.
Request:
message ListMethodsRequest {
string service = 1; // Service name
}
Response:
message ListMethodsResponse {
repeated MethodInfo methods = 1;
}
message MethodInfo {
string name = 1;
string full_name = 2;
string input_type = 3;
string output_type = 4;
bool is_client_streaming = 5;
bool is_server_streaming = 6;
}
Subscribe
Subscribes to one or more pub/sub topics. Server-streaming; defined on the Pubsub
service, not on Gateway.
Request:
message SubscribeRequest {
repeated string topics = 1; // Topics to subscribe to
google.protobuf.Timestamp replay_since = 2; // Optional: replay retained entries first
bool replay_only = 3; // Optional: only the replay, then the call ends
}
A subscription starts at each topic's tail: what was published before it opened is not
delivered, and everything published after it is. On the Redis backend a closed
subscription's leftover reader in daprd can take the next message on its topic
(common#28); the gateway
finds that message within seconds and delivers it to the topic's open subscription, 2-7 s
late and possibly out of order, instead of dropping it. To avoid that path, a topic's Dapr
subscription stays open PubsubSubscriptionLingerSeconds (default 10, 0 closes at once)
after its last caller left: a caller that subscribes again meanwhile joins it, so a quick
resubscribe never closes and reopens one. What is published while nobody is subscribed is
not delivered to a later caller (no catch-up). With replay_since set, the gateway first delivers every entry the topic's
stream still retains from that time on (the stream's own clock; Redis stream ids are
milliseconds), oldest first, and then the live messages, skipping a live message the
replay already delivered (matched by CloudEvent id). The response headers are sent once
the live subscription is active, before the replayed entries. Replay is meant for
low-rate topics that must survive a resubscription, such as a worker's command topic
while the WorkManager Runtime moves the worker to another pod; it reads the stream with
XRANGE and moves no consumer group. It needs the Redis pub/sub backend with
PubsubRedisHost configured (FAILED_PRECONDITION otherwise), and a topic that retains
more entries since then than PubsubReplayMaxEntries (default 10000), or more payload
bytes than PubsubReplayMaxBytes (default 64 MiB), is OUT_OF_RANGE; both fail before
the headers. The stream is read in pages of 256 entries and the read stops at the first
limit passed, so an overrun never loads the whole stream.
replay_only = 3 (with replay_since): the call delivers the retained entries and then
ends with OK; no live subscription is opened (no Dapr subscription, no consumer group).
For a subscriber that already receives the topic live and needs only what it missed: the
WorkManager Runtime catches a worker that moved to another pod up on its input topics
this way, merging the replay with its shared live stream by CloudEvent id. Without
replay_since it is INVALID_ARGUMENT.
Subscribefilters by topic only — there is no service or event-type filter on the wire. An emptytopicslist does not mean "all topics"; it defaults to["sys.api.state.saved", "sys.api.state.deleted"]. Discriminate further oncloudevent.type.
Response (stream):
message SubscribeResponse {
string topic = 1;
io.cloudevents.v1.CloudEvent cloudevent = 2;
}
Request/Response Examples
Using gRPC with C
using Grpc.Net.Client;
using Virtufin.Api.Protos;
// Create channel
var channel = GrpcChannel.ForAddress("http://localhost:5002");
var client = new Gateway.GatewayClient(channel);
// List services
var services = client.ListServices(new ListServicesRequest());
Console.WriteLine($"Services: {string.Join(", ", services.Services)}");
// Invoke a method
var invokeResponse = client.Invoke(new InvokeRequest
{
Service = "workmanager",
Method = "ListWorkers",
RequestData = "{}"
});
Console.WriteLine($"Success: {invokeResponse.Success}");
Console.WriteLine($"Response: {invokeResponse.ResponseData}");
Using gRPC with Python
import grpc
import gateway_pb2
import gateway_pb2_grpc
channel = grpc.insecure_channel('localhost:5002')
stub = gateway_pb2_grpc.GatewayStub(channel)
# List services
response = stub.ListServices(gateway_pb2.ListServicesRequest())
print(f"Services: {response.services}")
# Invoke a method
invoke_response = stub.Invoke(gateway_pb2.InvokeRequest(
service="workmanager",
method="ListWorkers",
request_data="{}"
))
print(f"Success: {invoke_response.success}")
Health check
curl http://localhost:5001/health
Dynamic Dispatch
The Gateway's InvokeJson RPC accepts a service name, method name, and
JSON-serialized request, and returns a JSON-serialized response. This
allows callers to invoke any backend RPC without importing the backend's
proto definition or generated stub. The Gateway uses gRPC reflection on
the target backend service to discover the method's request/response
types, marshals the JSON into the appropriate Protobuf message, invokes
the backend's gRPC method, and marshals the response back to JSON.
gRPC InvokeJson
# WorkManager.ListWorkers — no request fields
grpcurl -plaintext -import-path src/Virtufin.Api.Protos/proto -proto gateway.proto \
-d '{"service": "workmanager", "method": "ListWorkers", "request_data": "{}"}' \
localhost:5002 virtufin.Gateway/InvokeJson
More calls, the same way:
# WorkManager.CreateWorker -- CodeSource oneof (url | content), mime_type, topic
grpcurl -plaintext -import-path src/Virtufin.Api.Protos/proto -proto gateway.proto \
-d '{"service": "workmanager", "method": "CreateWorker", "request_data": "{\"code_source\":{\"url\":\"https://example.com/worker.py\"},\"mime_type\":\"text/x-python\",\"topic\":\"worker-commands\"}"}' \
localhost:5002 virtufin.Gateway/InvokeJson
# WorkManager.InvokeWorkerCommand -- a command to a running worker, answered with its outputs
# (here the status of a WebSocketFeed worker; payload is bytes, so base64 in JSON)
grpcurl -plaintext -import-path src/Virtufin.Api.Protos/proto -proto gateway.proto \
-d '{"service": "workmanager", "method": "InvokeWorkerCommand", "request_data": "{\"id\":\"<feed worker id>\",\"command\":\"status\"}"}' \
localhost:5002 virtufin.Gateway/InvokeJson
Response shape:
{
"success": true,
"status": "OK",
"message": "",
"response_data": "{\"workers\":[{\"id\":\"abc123\",\"status\":\"RUNNING\",\"language\":\"python\"}]}"
}
The response_data field is a JSON-encoded string of the backend's typed
proto response. Parse it client-side to get the typed fields.
See also: The per-language client docs (python-client.md,
csharp-client.md, typescript-client.md) for higher-level wrappers
around InvokeJson. The
proto-to-client-mapping spec
§Layer 4 documents the full call chain including gRPC reflection lookup
and JSON ↔ Protobuf marshaling.