gRPC + Postman = 😍

From a technology point of view gRPC is incredible. It nicely compliments the statically typed nature of Go with the proto file specification and code generation. Overall, gRPC has increased both the robustness and the discoverability of Weave’s internal APIs. One of the downsides to gRPC is the lack of developer friendly tooling for use during development.

One of the primary complaints from our transition to gRPC has been the inability to use Postman for our gRPC services. The existing tooling has not met the ease of use the Postman providing for interacting with our traditional REST APIs. We have tried the gRPC CLI, grpc-gateway, and omgRPC, created by one of our developers. Each of these options has slowly over time been abandoned, leading to less direct and more cumbersome methods of interacting with and exploring services.

Johan Brandhorst recently posted about adding a JSON codec to gRPC servers. While amazing, it wasn’t initially clear how this could be used to improve development workflows, especially given the reluctance of Postman to support HTTP/2 and the required binary header for the gRPC payload (whether a protocol buffer or JSON payload).

We introduce a way to use Postman with gRPC. We have created a proof of concept proxy which handles the protocol conversion from HTTP to HTTP/2 and also calculates and inserts the gRPC payload header. On the response , it trims the header off of the gRPC response and converts the gRPC status code to a HTTP status code. The introduction of this proxy allows us to once again use the incredible collaboration and templating features of Postman with our gRPC services!

Configuration of the proxy and its dependencies is a three step process.

1. Register a JSON codec with the gRPC server. At Weave, this is as easy as using the most current version of our internal library. In Go, it can be automatically registered simple by adding the following import:

import _"github.com/jnewmano/grpc-json-proxy/codec"

2. Run the grpc-json-proxy.

go get -u github.com/jnewmano/grpc-json-proxy 
grpc-json-proxy

3. Configure Postman to send requests through the proxy.

Postman -> Preferences -> Proxy -> Global Proxy
Proxy Server: localhost 7001

Postman proxy configuration

Using Postman with your gRPC service should then feel much more familiar:

1. Set request method to Post .
2. Set the URL to http://{{ grpc server address}}/{{proto package}}.{{proto service}}/{{method}} Always use http, proxy will establish a secure connection to the gRPC server.
3. Set the Content-Type header to application/grpc+json .
   Optionally add aGrpc-Insecure header set to true for an insecure connection.
4. Set the request body to appropriate JSON for the message. For reference, generated Go code includes JSON tags on the generated message structs.

For example:

Example Postman grpc+json request

In the future, Postman collections can be automatically generated and published during the CI/CD process from the source proto files. Additionally, the proxy can be configured to establish port-forwarding rules into Kubernetes automatically. With autogenerated collections and Postman compatibility we hope to greatly improve the development workflow.

Notes:

• github.com/jnewmano/grpc-json-proxy
• If you have custom types in Go you will need to implement the jsonpb.JSONPBMarshaler and jsonpb.JSONPBUnmarshaler interfaces, which are very similar to the json.Marshaler and json.Unmarshaler interfaces.
• Better support for TLS certificates will be coming soon
• Don’t forget to disable the Postman proxy config if the grpc-json proxy is not running