Transcoding gRPC to HTTP/JSON using Envoy

Posted on by  
Christophe Hesters

When building a service in gRPC you define the message and service definition in a .proto file. gRPC generates client, server and DTO implementations automatically for you in multiple languages. At the end of this post you will understand how to make your gRPC API also accessible via HTTP JSON by using Envoy as a transcoding proxy. You can test it out yourself by running the Java code in the attached github repo. For a quick introduction on gRPC itself, please read gRPC as an alternative to REST.

Once you have a working gRPC service, you can expose a gRPC service as an HTTP JSON API by simply adding some extra annotations to your service definition. Then you need a proxy that translates your HTTP JSON calls and passes them to your gRPC service. We call this process transcoding. Your service is then accessible via gRPC and via HTTP/JSON. I would prefer using gRPC most of the time because it’s more convenient and safer to work with type-safe generated code that follows the ‘contract’, but sometimes transcoding can come in handy:

  1. Your webapp can talk to your gRPC service using HTTP/JSON calls. is a JavaScript gRPC implementation that can be used from within the browser. This project is promising but is not yet mature.

  2. Because gRPC uses a binary format on the wire, it can be hard to see what is actually being sent and received. Exposing it as an HTTP/JSON API makes it easier to inspect a service by using for example cURL or postman.

  3. If you are using a language for which no gRPC compiler exists, you can access it via HTTP/JSON.

  4. It paves the way for a smoother adoption of gRPC in your projects, allowing other teams to gradually transition.

Continue reading →