Save, edit, and share gRPC request-response examples

You can save, edit, and share gRPC request-response pairs as examples. You can even create gRPC examples from scratch.

APIs can be complex, and so can the guidelines for using them. Examples help you understand APIs by capturing the request sent from the client and the response received from the server in a single visual snapshot. You can combine these snapshots in a request and store the request in a collection to illustrate how the API functions under different scenarios. Examples help API producers tell the world beautifully what their API is about.

Saving a gRPC example

This walkthrough creates and runs a unary request, then saves the response as a gRPC example.

If you are using the Postman web app, you must use the Postman Desktop Agent. See About the Postman Agent for more information.

1. In Postman, select New > gRPC to open a request in a new tab.

2. Select Enter Server URL and enter grpc.postman-echo.com.

3. Select the Select a method dropdown list. When the list of methods has loaded, select SayHello.

   

4. Save the gRPC request to a collection.

   gRPC examples can't be saved unless the request is in a collection.

5. Select Invoke. A reply message appears in the response section.

6. Select Save as Example. The saved example opens in a new tab and you can see the saved example under the request in the sidebar.

   

Editing a gRPC example

This walkthrough edits a gRPC example.

1. Create a unary gRPC request, save it in a collection, and save a gRPC example.

2. Select the gRPC example in the sidebar.

3. In the response section, select the Status code dropdown list and select 2 UNKNOWN. The response updates automatically.

   The status codes are automatically populated based on the protobuf (protocol buffers) schema.

   

4. Select Save.

Creating a gRPC example from scratch

This walkthrough uses a streaming method to create a gRPC example. Note how streaming method messages differ from unary method messages.

1. Create a gRPC request with the LotsOfReplies method (or any streaming method) and save it in a collection.

2. In the sidebar, hover over the gRPC request you created and select the more actions icon > Add example. An empty example opens in the workbench and appears below the request in the sidebar.

3. Select the Add a Message dropdown list and select Message stream. This creates a sample message stream automatically using the message structure defined in the protobuf schema.

   

4. Select Save.

Creating example-specific documentation

1. Create a gRPC request, save it in a collection, and save a gRPC example.

2. Select the gRPC example in the sidebar.

3. In the right sidebar, select the documentation icon .

4. Select Add example description.

5. Enter your documentation for the gRPC example. Your documentation automatically saves.

Using messages from saved examples

While invoking a request, you can work with message payloads stored in the examples. This not only enables you to test the example scenarios by yourself, but also speeds up your debugging workflow.

This walkthrough shows how you can invoke a client streaming request with messages stored in the examples:

1. Create a gRPC request with the LotsOfGreetings method, and save it in a collection.

2. Create an example for the request with two different "greeting" messages and save it.

   

3. Select the request and select Invoke.

4. Select the dropdown list next to Use Example Message. Both messages from the example appear.

   

5. Select a message from the dropdown list and select Send.

6. Open the dropdown list again and select a different message.