What is grpc-gateway?

gRPC-Gateway is a tool that lets you offer a traditional, JSON-based REST API alongside a modern gRPC API without building and maintaining two separate codebases. It automatically generates a proxy server that sits in front of your application, translating incoming RESTful web requests into the gRPC format your backend understands, and then translates the responses back to JSON. At a high level, the tool works by reading your service definitions written in Protocol Buffers, a language-agnostic way to describe data. You add small annotations to these definitions to map specific web URLs and HTTP methods (like a POST request to /v1/example) to your internal functions. The tool then generates a reverse-proxy server that handles the translation automatically. If you cannot modify the original definition files, you can also configure these URL mappings using an external file. This is primarily used by backend teams who want the performance and developer experience of gRPC internally, but need to support external clients or tools that expect a standard REST API. For example, a team might build an internal microservice architecture using gRPC for speed, but use this tool to expose a JSON API to a web frontend, a third-party integration partner, or tools that don't support gRPC natively. It also generates OpenAPI (Swagger) documentation, making it easy for outside developers to understand and test the available endpoints. A notable tradeoff of this approach is that it relies on generated code and proxy architecture rather than hand-writing HTTP endpoints. This means you define your API once, ensuring both the gRPC and REST interfaces stay perfectly in sync. The project also provides signed release binaries, allowing teams to securely verify that the downloaded code hasn't been tampered with.