gRPC

Load a server's gRPC services, write a request message as JSON and call any method, streaming ones included.

What gRPC is

gRPC is a way for programs to call functions on a server. Where a REST API has URLs and JSON, a gRPC API has services with methods, and it sends compact binary messages over HTTP/2.

The shape of every message is written down in a .proto file. A client needs that description to build a request and read the reply. ApiWorkbench gets it in one of two ways:

• Server reflection: the server tells the client which services it has. Nothing to import, but the server must have reflection turned on.
• .proto files: you give the app the files, or paste their text.

You write messages as JSON. The app converts them to and from the binary format.

Make your first call

You need a gRPC server with reflection turned on. This example uses grpcb.in:9000, a public test server without TLS. A server of your own on localhost:50051 works the same way.

1. In the tab bar, select the small arrow next to + and choose gRPC.

   A tab named New gRPC opens with localhost:50051 as the server address.

2. Type grpcb.in:9000 as the server address.

3. Make sure Use reflection is selected, then select the reload button next to the method picker (Load services).

   The app asks the server for its services. A line shows how many were found.

4. Pick a service, for example hello.HelloService, and then a method marked unary.

5. On the Message tab, select Generate example message.

   The editor fills with every field of the request type. Change the values as you like.

6. Select Invoke.

   The lower pane shows the request message, the response message, any metadata and the final status. 0 OK means the call succeeded.

Good to know

Public test servers can change or go away. If the services do not load, try your own server, or switch to Import .proto files.

Server address

Type the server as host:port.

• grpcs:// (or https://) in front turns TLS on.
• http:// in front turns TLS off.
• A bare host:port or grpc:// follows the Use TLS switch on the Settings tab.

Variables such as {{grpcHost}} are allowed.

Load services by reflection

With Use reflection selected, the app uses gRPC server reflection (grpc.reflection.v1, or v1alpha on older servers). Select Load services now on the Proto tab, or the reload button, whenever the server changes.

If loading fails, the log says Could not load services with the reason. The most common causes are a wrong address, the wrong TLS setting, or a server with reflection turned off.

Load services from .proto files

1. Select Import .proto files above the tabs.

2. Open the Proto tab and select Add .proto files. Choose one or more files.

3. If your files import others that are not next to them, select Add import folder and choose the folder the imports are relative to. This is the same idea as the -I option of protoc.

4. Select Load services.

Imports are looked up next to the importing file, then in its parent folders, then in the import folders. The well-known Google types, such as google/protobuf/timestamp.proto, are built in. Loaded files lists every file of the current schema.

You can also type or paste a definition under Paste a definition. It is used together with the files, and is handy on a phone.

WARNING

The request stores the paths of your .proto files, not copies. If you move the files, or open the collection on another computer, add them again. The Snap package can read files in your home folder and on removable media only.

The four call types

The method picker tags each method with its kind.

Kind	What happens	How to use it
unary	One request, one response.	Write the message and select Invoke.
server stream	One request, many responses.	Select Invoke. Responses are listed as they arrive.
client stream	Many requests, one response.	Invoke opens the stream. Send each message, then End stream to get the reply.
bidi stream	Many requests and many responses, in any order.	Invoke opens the stream. Send messages as often as you like, then End stream.

While a call is running, Invoke becomes Cancel. Cancelling stops the call at once, and the server sees it as cancelled.

Write the message

The Message tab takes the request as JSON, in the proto3 JSON format:

• 64-bit numbers are written as strings: "id": "42".
• bytes fields are written as base64.
• Enum values are written by name.

Leave the editor empty or {} to send an empty message. Variables are filled in before sending. Format re-indents the JSON. If the message does not fit the request type, the call is not sent and the log explains which field is wrong.

Metadata

Metadata is gRPC's version of headers. On the Metadata tab, select Add metadata and enter a key and a value, for example authorization and Bearer {{token}}.

Write keys in lower case. A key that ends in -bin carries a base64 binary value. Unticked rows are kept but not sent.

TLS, deadline and display settings

Setting	What it does	Default
Use TLS	Encrypts the connection. Off sends plaintext HTTP/2, as most local development servers expect. A grpcs:// or http:// address overrides it.	Off
Verify the certificate	Checks that the server's TLS certificate is valid and trusted. Turn it off for self-signed certificates in development.	On
Show default values	Lists response fields that hold their default (0, "", false, empty lists), which protobuf does not send.	On
Deadline (ms)	The call ends with DEADLINE_EXCEEDED if it takes longer, streams included. Empty waits as long as the server takes.	None

gRPC tabs use these settings, not the proxy and certificate settings of the app.

Read the result

The lower pane is a timeline of the call. Each entry shows its size and the time since you selected Invoke.

• Request and response messages, as JSON.
• Metadata sent at the start, and metadata the server sent after its last message.
• The final status as a number and a name.

Common statuses:

Status	Meaning
0 OK	The call finished successfully.
1 CANCELLED	The call was cancelled before it finished.
3 INVALID_ARGUMENT	The server rejected the request message as invalid.
4 DEADLINE_EXCEEDED	The deadline passed before the call finished.
5 NOT_FOUND	The server could not find what was asked for.
7 PERMISSION_DENIED	The caller is not allowed to do this.
12 UNIMPLEMENTED	The server does not implement this method.
13 INTERNAL	Something broke on the server.
14 UNAVAILABLE	The server could not be reached, or dropped the connection. Check the address and the TLS setting.
16 UNAUTHENTICATED	Missing or invalid credentials. Check the metadata.

Copy response copies the last response message as JSON. Clear empties the timeline; a call in progress keeps running.

Next steps

• WebSocket
• Variables
• Troubleshooting