Skip to content

Explore gRPC APIs

Use grpcui as the browser-based API explorer. It discovers schemas through gRPC reflection, renders request forms and shows RPC responses and metadata. It runs on your machine, separately from the backend: the services serve only gRPC (and gRPC-Web on the gateway) plus their health probes.

Install grpcui and run the shared launcher from the common repo:

bash common/scripts/run_grpcui_local.sh localhost:5002

The target defaults to localhost:5002, the API's gRPC port (5001 is its HTTP health port). The browser UI binds to 127.0.0.1 on an automatically selected port. HOST, PORT, UI_PORT and TLS configure the launcher; an explicit endpoint and additional grpcui flags are accepted. --help lists the options.

Remote targets

Remote APIs require authentication for reflection as well as for calls. Set VIRTUFIN_API_KEY and the launcher sends it as the x-api-key header:

export VIRTUFIN_API_KEY=...   # from your secret store, not shell history
TLS=true bash common/scripts/run_grpcui_local.sh api.virtufin.com:443
  • The key is sent in cleartext only to a loopback host (for example a kubectl port-forward); to any other host the launcher requires TLS=true.
  • grpcui accepts headers only as command-line flags, so the key is visible in the process list of the machine running the UI. Use it on your own machine, not a shared host.
  • Keep the UI private: it can invoke mutating methods with your key. Never publish an authenticated grpcui proxy.

What is callable where

All backend services keep gRPC reflection. The gateway's aggregated reflection lists backend descriptors, but that does not make each backend RPC directly callable on the gateway: use Gateway.Invoke/InvokeJson, or a port-forward to the backend's gRPC endpoint.

For command-line discovery:

grpcurl -plaintext localhost:5002 list
grpcurl -plaintext localhost:5002 describe virtufin.Gateway

Static reference

The generated protobuf and SDK documentation remains the shareable static reference. Proto files and binary descriptor sets are the machine-readable gRPC contracts; grpcui can use them when reflection is unavailable.