Skip to content

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


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.

Subscribe filters by topic only — there is no service or event-type filter on the wire. An empty topics list does not mean "all topics"; it defaults to ["sys.api.state.saved", "sys.api.state.deleted"]. Discriminate further on cloudevent.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.