Invoke a gRPC request in Postman

This guide describes how to create and invoke a gRPC request in Postman using the Postman Echo service for gRPC. The procedure below uses a unary method and shows how to add an example message to your request. There are also some troubleshooting tips in case you encounter any issues.

About gRPC API requests

APIs provide a structured way for one application to access the capabilities of another application. Typically, this communication happens over the internet by way of an API server. A client application (like a mobile app) sends a request to the server, and after the request processes, the server returns a response to the client.

A gRPC request consists of the server URL where the service is hosted, the method to be invoked on the server, and a request payload that has the message and required information on how the request will be executed. Since gRPC is a schema-driven framework, the request also needs to have a service definition (schema) reference that has information on the services, methods, message fields, and data types supported by the server. The client must follow the service definition to avoid errors.

The Postman API client supports four types of gRPC methods that enable the client and server to interact in different ways depending on the required use case:

• Unary - This is the traditional request-response communication pattern also seen in HTTP where the client makes a request and the server returns a response.

• Client streaming - The client sends a series of messages to the server and the server returns a response after processing them.

• Server streaming - The client makes a single request and the server returns a response with a stream of messages.

• Bidirectional streaming - The client and server communicate with each other asynchronously over a persistent session.

Creating and invoking a request

This example creates and executes a unary request. To learn about invoking the other method types, see The gRPC interface.

If you are using the Postman web app, Postman recommends using the Postman Desktop Agent for the best experience. See About the Postman Agent for more information.

1. In a Postman workspace, select New > gRPC to open a request in a new tab. (In the Postman desktop app, you can also select ⌘+N or Ctrl+N, then select gRPC.)

   

2. Select Enter URL and enter a URL. For this example, use the Postman Echo service for gRPC, which is grpc.postman-echo.com.

3. Select Select a method and browse through the supported services and methods. When you enter the URL, Postman automatically loads the service definition using server reflection (if supported by the server). If server reflection isn't supported on the server, you will have to load the service definition manually. Learn more about working with service definitions.

4. From the list of methods, select SayHello. This is a unary method.

5. In the Message area, select Use Example Message. This creates an example message using the service definition itself so that you don’t have to set the correct fields and data types.

6. Replace the sample string data with your name (or any other string) and select Invoke.

Once the method is invoked, the server processes the information passed and returns a response.

Troubleshooting

If you encounter a problem with a gRPC request, the following troubleshooting steps may help you identify and resolve the issue:

• Service unavailable The server you're using is unreachable with the current client settings. If you've confirmed the server is working, check the TLS settings in the client. By default, TLS is turned off.

• Server reflection failed Check if server reflection is supported by the server, check the TLS settings of the request, or retry server reflection by using Service definition > Use server reflection > Try again.

• Switch to Postman Desktop Agent to connect with a gRPC server To use all of Postman's gRPC features, you must run the Postman Desktop Agent. Learn more about installing the Postman Desktop Agent.

For more troubleshooting information, see Troubleshoot app issues and Debug API requests in Postman.

Next steps

Try invoking some other methods available on grpc.postman-echo.com and see how things act differently.

When you’re done, learn about managing service definitions for gRPC requests.