It has taken me far too long to figure out all the minute details of how to apply authentication to gRPC-based services, how to do that using the HTTP/JSON grpc-gateway, and then how to run a gRPC server and a grpc-gateway side-by-side using the same service instance in a way that makes sense to me.

There’s a surprising amount of detail that is not documented and there are a few gotchas for the unwary traveller. For example, grpc-gateway, even with default settings, simply ignores the Content-Type of POST, PUT & PATCH requests, so it will try to process anything its been given as a JSON request body. This is a surprise that had me stumped for longer than I care to acknowledge. This by no means meant as a slight on a project that makes it possible for me to create a protobuf service definition, HTTP endpoints from the definition, and then implement said service in Go without all that tedious marshalling & unmarshalling to & from JSON. It does however mean that it is up to you to ensure that your service obeys the Content-Type if that is important for you.

The benefit from being able to use the same implementation for a gRPC service and a HTTP/JSON service is huge. To make it easier for me to remember, and to share what I’ve managed to find, I’ve created a GitHub project called example-grpc. Hopefully this will be able to show you via working code how to generate the services, how to wire them all together, and how to do that using authentication that works for both HTTP and gRPC.

I also had a bit of fun setting up various clients to test both the gRPC and the HTTP APIs. The biggest finds of the day were grpcurl and gRPC server reflection which make it much easier to introspect and test gRPC APIs.

Hope you find this as useful as I did.