Skip to Content

gRPC

gRPC is a high-performance RPC framework built on HTTP/2 and Protocol Buffers. A service and its methods are defined in a .proto file, and clients call those methods with typed messages. It is widely used for communication between microservices.

With a gRPC Request, you import the proto file, pick a method, write the request as JSON, and Thunder Client handles the encoding for you.

gRPC support is in Beta.

Call Types

Thunder Client supports all four gRPC call types.

Call typeLabelClient sendsServer sendsExample
Unary—One messageOne messageGetUser
Server streamingServerOne messageA stream of messagesTrackOrder
Client streamingClientA stream of messagesOne messageUploadReadings
Bidirectional streamingBi-dirA stream of messagesA stream of messagesChat

Make Your First Call

Create a gRPC request

In the sidebar, click the arrow next to New Request and select gRPC Request (Beta).

New Request menu with gRPC Request (Beta) highlighted

Import the proto file

In the Import tab, click Choose File to import a .proto file from your computer, or click the import icon to download one from a URL.

Enter the server address

Enter the address as host:port, for example localhost:50051. Do not include http:// or https://.

Select a method

Choose a method from Select Method. Streaming methods are labeled Server, Client, or Bi-dir.

Write the request message

In the Message tab, write the request as JSON. Click Generate Example to create a sample message from the proto definition, then edit the values.

{ "orderId": "ORD-1001" }

Invoke

Click Invoke. The response appears on the right, along with the status.

Manage Proto Files

A request can use more than one proto file.

  • Select Proto — Switch between the imported proto files.
  • Reload — Click the reload icon next to Select Proto to pick up changes after you edit a proto file.
  • Clear all — Remove all imported proto files from the request.
Proto files imported from a URL are downloaded to your Documents folder.

Streaming

  • Server streaming — Click Invoke. Each message from the server is added to the response as it arrives, until the server ends the stream.
  • Client and bidirectional streaming — Click Invoke to open the stream and send the first message. Edit the message and click Send to send more while the stream is open. Click Stop to end the stream.
gRPC server streaming call to OrderService.TrackOrder with four streamed order updates

Metadata, Auth, and TLS

  • Metadata — Use the Metadata tab to send gRPC metadata, the gRPC equivalent of HTTP headers. Metadata returned by the server is shown with the response.
  • Auth — Basic and Bearer auth are sent as Authorization metadata. For other schemes, such as API keys, add them in the Metadata tab.
  • TLS — Check Enable TLS in the Import tab to connect over TLS using your system’s trusted certificates. Leave it unchecked for plaintext connections, which are common in local development.

Errors and Status Codes

When a call fails, the response shows the gRPC status code and the error details from the server. Common codes:

CodeNameUsual cause
3INVALID_ARGUMENTA field in the message is missing or invalid.
5NOT_FOUNDThe requested resource does not exist.
12UNIMPLEMENTEDThe server does not implement this method. Check that the proto file matches the server.
14UNAVAILABLEThe server cannot be reached. Check the address, port, and Enable TLS.
16UNAUTHENTICATEDCredentials are missing or invalid.

Limitations

While gRPC is in Beta, these HTTP features are not available for gRPC requests:

  • Environment variables. Enter the server address, metadata, and message values directly.
  • The Tests and Pre Run tabs.
  • Code snippets.
  • Auth types other than Basic and Bearer.
  • Server reflection. Import the .proto file for the service instead.

Troubleshooting

ProblemWhat to check
Select Method is emptyThe proto file did not load, or it defines no services. Import the file again and check it for errors.
UNAVAILABLE or a connection errorCheck host:port, and match Enable TLS to the server: on for TLS servers, off for plaintext.
A proto file with imports fails to loadMake sure the imported files are available alongside it.
Changes to the proto file are not showingClick the reload icon next to Select Proto.
Last updated on