Show your gRPC APIs in action with examples

Shobhit Katikia

February 23, 2023

To enrich your API documentation and make your API experience even more delightful, we’ve just extended support for examples to Postman’s gRPC client. You may already be familiar with examples in HTTP requests and the value they deliver in the API lifecycle. Now, we’re excited to see how you use them to build your gRPC APIs.

APIs can be complex, and so can the guidelines to use them. You can break this complexity down by taking snapshots of the request sent from the client and the response received from the server and representing them visually with examples. A combination of these examples can be created in a request and stored in a collection to illustrate how the API functions under different scenarios.

Illustrate your API’s capabilities while it’s still a work in progress

Let’s say your team is ready with the design of the API, but it’s yet to be developed. Meanwhile, the consumers want to get started on the applications and don’t want to wait. Examples can break this dependency by showing how the API is supposed to work. You can create examples from scratch depicting scenarios where the server returns a response for specific request configurations. Postman makes this task even easier for you by allowing you to use the power of schema and generate example responses. Once you’re done composing the example, you can also add a description to be a little more specific about the example scenarios.

Document an existing API

With examples, you can document an API that’s already up and running and demonstrate its abilities. Send requests to the server with the request configurations you wish to document, and once the server responds back, save the request/response pairs as examples. This means you don’t have to spend time creating long explanations for documenting your API’s behavior. Plus, you don’t have to worry about consumers not having permission to test the API themselves.

Augment the request-sending experience with Examples

Examples can be more effective than simple static documentation chunks. Content from examples can power the real-time execution of an API, crafting a much more intuitive and fulfilling consumption experience. Imagine a consumer being able to test the potential scenarios themselves instead of reading through the static snapshots. Thrilling, right? So, starting with gRPC requests, we have introduced a way for our users to try out the API with documented messages from the examples. Click on the down-arrow button next to the Use Example Message button, select a message from one of the examples, and hit Invoke!

Apart from this, we are also bringing examples closer to request documentation so that consumers can quickly see how the request functions without having to open every single example individually. This saves time by conveying the most necessary information at a glance.

Example interface curated just for gRPC

gRPC is adored by developers for its nifty characteristics, such as being schema-driven and enabling APIs to perform effectively across a range of communication patterns; unary, client-streaming, server-streaming, and bidirectional-streaming. While building the example support, we preserved the usefulness of examples observed in HTTP requests while ensuring that the interface doesn’t lose out on the fundamentals of gRPC. When a streaming-type method is selected, the response area in the example turns into a message stream editor. You can add multiple messages to it, switch between the message types (whether sent or received), and reorder them as you need to tell the story you want.

Plus, example composition is leveled up with the help of a Protobuf definition. As you saw earlier in this post, you can speed up your documentation process using the Generate Example Response button in the response area. This generates a JSON message based on the configured Protobuf definition documenting the message structure using mock data. This feature shines even brighter when you’re authoring a streaming-type example. Based on the method type selected, Postman generates an entire stream of messages for you.

Learn more

Get a hands-on experience of what examples for gRPC requests feel like with these helpful collections in the Postman Public API Network:

• Postman gRPC echo collection: Postman’s official echo service to demonstrate the power of gRPC.
• Cisco IOS-XR gRPC/gNMI by Cisco Technical Lead Nick Russo: Example gRPC requests/responses for Cisco IOS-XR using the XR-specific proto file along with the OpenConfig (OC) gNMI standard.

Try Postman now