API Reference

Complete API documentation for the Virtufin API gateway.

Generated API Documentation

C# SDK Reference — Auto-generated docs for Virtufin.Api and Virtufin.Api.Client
Python SDK Reference — Auto-generated docs for virtufin package
TypeScript SDK Reference — Auto-generated docs for TypeScript client

REST API Endpoints

Configuration Endpoints

List All Services

GET /v1/config/list-services

Returns configuration for all registered services.

Response:

{
  "services": [
    {
      "name": "workmanager",
      "daprAppId": "",
      "grpc": {
        "host": "localhost",
        "port": 5002
      },
      "pubsub": {
        "pubsubName": "pubsub"
      },
      "state": {
        "storeName": "statestore",
        "keys": ["workmanager/workers/index"]
      },
      "jobs": {
        "crons": []
      }
    }
  ]
}

Important: Each service in the config must have gRPC reflection enabled on its gRPC port. The API Gateway uses reflection for method discovery, schema validation, and dynamic invocation. If a backend service does not support gRPC reflection, the gateway cannot proxy requests to it.

Get Service Configuration

GET /v1/config/get-service?name={serviceName}

Parameters: - name (required): The service name

Response: Single ConfigService object or null if not found.

Gateway Endpoints

List Services

GET /v1/gateway/list-services

Lists all services registered with the gateway.

Response:

{
  "services": ["workmanager", "websocketmanager"]
}

List Methods

GET /v1/gateway/list-methods?service={serviceName}

Parameters: - service (required): The service name

Response:

{
  "methods": [
    {
      "name": "GetWorker",
      "fullName": "virtufin.workmanager.GetWorker",
      "inputType": "virtufin.GetWorkerRequest",
      "outputType": "virtufin.GetWorkerResponse",
      "isClientStreaming": false,
      "isServerStreaming": false
    }
  ]
}

Invoke Method (REST)

POST /v1/gateway/invoke
Content-Type: application/json

{
  "service": "workmanager",
  "method": "GetWorker",
  "requestData": { "workerId": "123" }
}

gRPC Reflection Endpoints

Get Service Methods

GET /v1/grpc/{service}/methods

Returns methods for the specified service.

Response:

[
  {
    "name": "GetWorker",
    "inputType": "virtufin.GetWorkerRequest",
    "outputType": "virtufin.GetWorkerResponse",
    "streamingType": "unary"
  }
]

Streaming Types: - unary - Single request, single response - server - Server-side streaming - client - Client-side streaming - bidi - Bidirectional streaming

Get Method Schema

GET /v1/grpc/{service}/schema/{method}?type=input

Returns the schema (field definitions) for a method's input or output type.

Parameters: - type (optional): input or output (default: input)

Response:

{
  "inputTypeName": "virtufin.GetWorkerRequest",
  "outputTypeName": "virtufin.GetWorkerResponse",
  "schemaType": "input",
  "fields": [
    {
      "name": "workerId",
      "type": "String",
      "typeName": "",
      "isRepeated": false,
      "isOptional": false
    }
  ]
}

Execute gRPC Call

POST /v1/grpc/call
Content-Type: application/json

{
  "service": "workmanager",
  "method": "GetWorker",
  "request": "{\"workerId\": \"123\"}"
}

Response:

{
  "error": false,
  "statusCode": "OK",
  "data": "{\"name\": \"Worker 123\", \"status\": \"active\"}"
}

Get Protocol Buffer Descriptors

GET /v1/grpc/{service}/protos

Returns the raw protocol buffer descriptors for a service (in protobuf binary format).

State Endpoints

Save State

POST /v1/state/save-state
Content-Type: application/json

{
  "service": "workmanager",
  "key": "workers/index",
  "value": "{\"activeWorkers\": 5}",
  "etag": "optional-etag",
  "include_value": false
}

Parameters: - service (required): Service name - key (required): State key - value (required): State value as string - etag (optional): ETag for concurrency control - include_value (optional, default: false): If true, the value is included in the state change event payload

Response:

{
  "status": {
    "success": true,
    "status": "OK",
    "message": "State saved for workmanager/workers/index"
  }
}

Get State Value

GET /v1/state/{service}/{key}

Retrieves a state value for a service.

Parameters: - service - Service name - key - State key

Response:

{
  "key": "workers/index",
  "value": "{\"activeWorkers\": 5}",
  "etag": "..."
}

Get All State for Service

GET /v1/state/{service}

Returns all registered state keys for a service. Keys are registered dynamically via State.RegisterKeys RPC or automatically tracked on first use.

Response:

{
  "values": {
    "key1": "value1",
    "key2": "value2"
  }
}

Delete State

DELETE /v1/state/{service}/{key}

Deletes a state entry and publishes a delete event.

Parameters: - service - Service name - key - State key - include_value (optional, query param): If true, includes the last value in the event payload

Response:

{
  "status": {
    "success": true,
    "status": "OK",
    "message": "State deleted for workmanager/my-key"
  }
}

See Events Documentation for event streaming details.

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
`Subscribe`	`SubscribeRequest`	stream `TopicEventRequest`	Subscribe to topic events

State Service (`virtufin.State`)

Method	Request	Response	Description
`SaveState`	`SaveStateRequest`	`SaveStateResponse`	Save state and publish event
`GetState`	`GetStateRequest`	`GetStateResponse`	Get a single state value
`GetAllState`	`GetAllStateRequest`	`GetAllStateResponse`	Get all state for a service
`RegisterKeys`	`RegisterKeysRequest`	`RegisterKeysResponse`	Register state keys
`DeleteState`	`DeleteStateRequest`	`DeleteStateResponse`	Delete state and publish event

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;
}

Subscribes to events matching the specified criteria. Returns a streaming response.

Request:

message SubscribeRequest {
  repeated string services = 1;    // Filter by services
  repeated string topics = 2;      // Filter by topics
  repeated string event_types = 3; // Filter by event types
}

Response (stream):

message TopicEventRequest {
  string id = 1;
  string source = 2;
  string type = 3;
  string spec_version = 4;
  string data_content_type = 5;
  bytes data = 7;
  string topic = 6;
  string pubsub_name = 8;
  string path = 9;
}

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}")

Using REST with curl

# List services
curl http://localhost:5001/v1/gateway/list-services

# Get service configuration
curl http://localhost:5001/v1/config/get-service?name=workmanager

# Get method schema
curl http://localhost:5001/v1/grpc/workmanager/methods

# Get state
curl http://localhost:5001/v1/state/workmanager/workers/index

# 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

REST: POST to `/v1/gateway/invoke-json`

# WorkManager.ListWorkers
curl -X POST http://localhost:5001/v1/gateway/invoke-json \
  -H "Content-Type: application/json" \
  -d '{
    "service": "workmanager",
    "method": "ListWorkers",
    "request_data": "{}"
  }'

# WorkManager.CreateWorker — CodeSource oneof (url | content), mime_type, topic
curl -X POST http://localhost:5001/v1/gateway/invoke-json \
  -H "Content-Type: application/json" \
  -d '{
    "service": "workmanager",
    "method": "CreateWorker",
    "request_data": "{\"code_source\":{\"url\":\"https://example.com/worker.py\"},\"mime_type\":\"text/x-python\",\"topic\":\"worker-commands\"}"
  }'

# WebSocketManager.List — no request fields
curl -X POST http://localhost:5001/v1/gateway/invoke-json \
  -H "Content-Type: application/json" \
  -d '{
    "service": "websocketmanager",
    "method": "List",
    "request_data": "{}"
  }'

# WebSocketManager.Connect — url, auto_reconnect
curl -X POST http://localhost:5001/v1/gateway/invoke-json \
  -H "Content-Type: application/json" \
  -d '{
    "service": "websocketmanager",
    "method": "Connect",
    "request_data": "{\"url\":\"wss://stream.example.com/feed\",\"auto_reconnect\":true}"
  }'

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.

API Reference

Generated API Documentation

Table of Contents

REST API Endpoints

Configuration Endpoints

List All Services

Get Service Configuration

Gateway Endpoints

List Services

List Methods

Invoke Method (REST)

gRPC Reflection Endpoints

Get Service Methods

Get Method Schema

Execute gRPC Call

Get Protocol Buffer Descriptors

State Endpoints

Save State

Get State Value

Get All State for Service

Delete State

Health Check

gRPC Services

Gateway Service (virtufin.Gateway)

State Service (virtufin.State)

Config Service (virtufin.Config)

Gateway Service Methods

Invoke

ListServices

ListMethods

Subscribe

Request/Response Examples

Using gRPC with C

Using gRPC with Python

Using REST with curl

Dynamic Dispatch

gRPC InvokeJson

REST: POST to /v1/gateway/invoke-json

Gateway Service (`virtufin.Gateway`)

State Service (`virtufin.State`)

Config Service (`virtufin.Config`)

REST: POST to `/v1/gateway/invoke-json`