gRPC to JSON proxy generator following the gRPC HTTP spec

go, grpc, grpc-gateway, openapi, rest-api, restful-api, swagger
go get



Build Status

grpc-gateway is a plugin of protoc. It reads gRPC service definition, and generates a reverse-proxy server which translates a RESTful JSON API into gRPC. This server is generated according to custom options in your gRPC definition.

It helps you to provide your APIs in both gRPC and RESTful style at the same time.

architecture introduction diagram


gRPC is great -- it generates API clients and server stubs in many programming languages, it is fast, easy-to-use, bandwidth-efficient and its design is combat-proven by Google. However, you might still want to provide classic RESTful APIs too for some reasons -- compatibility with languages not supported by gRPC, API backward-compatibility or aesthetics of RESTful architecture.

That's what grpc-gateway helps you to do. You just need to implement your gRPC service with a small amount of custom options. Then the reverse-proxy generated by grpc-gateway serves RESTful API on top of the gRPC service.


First you need to install ProtocolBuffers 3.0.0-beta-3 or later.

mkdir tmp
cd tmp
git clone
cd protobuf
make check
sudo make install

Then, go get -u as usual.

go get -u
go get -u
go get -u


Make sure that your $GOPATH/bin is in your $PATH.

  1. Define your service in gRPC


    syntax = "proto3";
    package example;
    message StringMessage {
     string value = 1;
    service YourService {
     rpc Echo(StringMessage) returns (StringMessage) {}
  2. Add a custom option to the .proto file


    syntax = "proto3";
    package example;
    +import "google/api/annotations.proto";
    message StringMessage {
      string value = 1;
    service YourService {
    -  rpc Echo(StringMessage) returns (StringMessage) {}
    +  rpc Echo(StringMessage) returns (StringMessage) {
    +    option (google.api.http) = {
    +      post: "/v1/example/echo"
    +      body: "*"
    +    };
    +  }
  3. Generate gRPC stub

    protoc -I/usr/local/include -I. \
     -I$GOPATH/src \
     -I$GOPATH/src/ \
     --go_out=Mgoogle/api/,plugins=grpc:. \

    It will generate a stub file path/to/your_service.pb.go.

  4. Implement your service in gRPC as usual

    1. (Optional) Generate gRPC stub in the language you want.


      protoc -I/usr/local/include -I. \
       -I$GOPATH/src \
      -I$GOPATH/src/ \
      --ruby_out=. \
      protoc -I/usr/local/include -I. \
       -I$GOPATH/src \
      -I$GOPATH/src/ \
      --plugin=protoc-gen-grpc-ruby=grpc_ruby_plugin \
      --grpc-ruby_out=. \
    2. Implement your service
  5. Generate reverse-proxy

    protoc -I/usr/local/include -I. \
     -I$GOPATH/src \
     -I$GOPATH/src/ \
     --grpc-gateway_out=logtostderr=true:. \

    It will generate a reverse proxy path/to/

  6. Write an entrypoint

    Now you need to write an entrypoint of the proxy server.

    package main
    import (
     gw "path/to/your_service_package"
    var (
     echoEndpoint = flag.String("echo_endpoint", "localhost:9090", "endpoint of YourService")
    func run() error {
     ctx := context.Background()
     ctx, cancel := context.WithCancel(ctx)
     defer cancel()
     mux := runtime.NewServeMux()
     opts := []grpc.DialOption{grpc.WithInsecure()}
     err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *echoEndpoint, opts)
     if err != nil {
       return err
     http.ListenAndServe(":8080", mux)
     return nil
    func main() {
     defer glog.Flush()
     if err := run(); err != nil {
  7. (Optional) Generate swagger definitions

    protoc -I/usr/local/include -I. \
     -I$GOPATH/src \
     -I$GOPATH/src/ \
     --swagger_out=logtostderr=true:. \

Parameters and flags

protoc-gen-grpc-gateway supports custom mapping from Protobuf import to Golang import path. They are compatible to the parameters with same names in protoc-gen-go.

protoc-gen-grpc-gateway also supports some more command line flags to control logging. You can give these flags together with parameters above. Run protoc-gen-grpc-gateway --help for more details about the flags.

More Examples

More examples are available under examples directory.

  • examplepb/echo_service.proto, examplepb/a_bit_of_everything.proto: service definition
    • examplepb/echo_service.pb.go, examplepb/a_bit_of_everything.pb.go: [generated] stub of the service
    • examplepb/, examplepb/ [generated] reverse proxy for the service
  • server/main.go: service implementation
  • main.go: entrypoint of the generated reverse proxy

To use the same port for custom HTTP handlers (e.g. serving swagger.json), gRPC-gateway, and a gRPC server, see this code example by CoreOS (and its accompanying blog post)



  • Generating JSON API handlers
  • Method parameters in request body
  • Method parameters in request path
  • Method parameters in query string
  • Mapping streaming APIs to JSON streams
  • Mapping HTTP headers with Grpc-Metadata- prefix to gRPC metadata
  • Optionally emitting API definition for Swagger.
  • Setting gRPC timeouts through inbound HTTP Grpc-Timeout header.

Want to support

But not yet.

  • bytes and enum fields in path parameter. #5
  • Optionally generating the entrypoint. #8
  • import_path parameter

No plan to support

But patch is welcome.

  • Method parameters in HTTP headers
  • Handling trailer metadata
  • Encoding request/response body in XML
  • True bi-directional streaming. (Probably impossible?)

Mapping gRPC to HTTP

  • How gRPC error codes map to HTTP status codes in the response
  • HTTP request source IP is added as X-Forwarded-For gRPC request header
  • HTTP request host is added as X-Forwarded-Host gRPC request header
  • HTTP Authorization header is added as authorization gRPC request header
  • Remaining HTTP header keys are prefixed with Grpc-Metadata- and added with their values to gRPC request header




grpc-gateway is licensed under the BSD 3-Clause License. See LICENSE.txt for more details.