Skip to content
gRPC to JSON proxy generator following the gRPC HTTP spec
Go Python Makefile Other
Branch: master
Clone or download
Jeremytjuh and johanbrandhorst Use Go templates in protofile comments (#1056)
* use GO templates in protofile comments

* Added support for the other swagger documentation fields

* Added feature for Go templates in imported files

* Fixed typo in main.go

Co-Authored-By: Johan Brandhorst <johan.brandhorst@gmail.com>

* Added Go template example

* Added Go template documentation

* Generated examples using build image

* Generated bazel files using build image

* Added use_go_templates.pb.gw.go in build file

* Enhanced documentation

* Fixed indents

* Edited Go template bazel test

* Excluded use_go_template.pb.gw.go in buildfile
Latest commit c3787b4 Oct 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.bazelci Disable Windows CI Bazel Aug 15, 2019
.circleci Add back bzip2 to image Oct 9, 2019
.github Configure stale[bot] Sep 9, 2019
bin Replace travis with Circle-CI Oct 10, 2018
codegenerator Update rules_go and gazelle (#802) Nov 13, 2018
docs Use Go templates in protofile comments (#1056) Oct 21, 2019
examples Use Go templates in protofile comments (#1056) Oct 21, 2019
internal Update dependencies (#1053) Oct 2, 2019
protoc-gen-grpc-gateway Use Go templates in protofile comments (#1056) Oct 21, 2019
protoc-gen-swagger Use Go templates in protofile comments (#1056) Oct 21, 2019
runtime Support json names in field mask generation (#1050) Sep 30, 2019
third_party/googleapis New proposal: support for the google.api.HttpBody (#904) Mar 11, 2019
utilities Feature/patch2 rebased (#812) Nov 19, 2018
.gitignore Switch to go modules Feb 19, 2019
.goreleaser.yml Fix release script Aug 6, 2019
BUILD Update to rules_go and buildtools (#956) Jun 18, 2019
CHANGELOG.md Generate chagenlog for 1.11.3 Sep 30, 2019
CONTRIBUTING.md Remove "make test" recommendation from CONTRIBUTING.md Oct 2, 2019
ISSUE_TEMPLATE.md Update ISSUE_TEMPLATE.md (#1014) Sep 10, 2019
LICENSE.txt add license Apr 7, 2015
Makefile Use Go templates in protofile comments (#1056) Oct 21, 2019
README.md Update README.md Sep 10, 2019
WORKSPACE Update test swagger generator to 2.4.8 (#1058) Oct 4, 2019
fuzzit.sh Fuzzit: use go-fuzz with go-modules support Aug 31, 2019
go.mod Update test swagger generator to 2.4.8 (#1058) Oct 4, 2019
go.sum Update test swagger generator to 2.4.8 (#1058) Oct 4, 2019
repositories.bzl Update test swagger generator to 2.4.8 (#1058) Oct 4, 2019

README.md

grpc-gateway

release CircleCI fuzzit coverage license

The grpc-gateway is a plugin of the Google protocol buffers compiler protoc. It reads protobuf service definitions and generates a reverse-proxy server which 'translates a RESTful HTTP API into gRPC. This server is generated according to the google.api.http annotations in your service definitions.

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

architecture introduction diagram

Check out our documentation!

Background

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 a traditional RESTful JSON API as well. Reasons can range from maintaining backwards-compatibility, supporting languages or clients not well supported by gRPC, to simply maintaining the aesthetics and tooling involved with a RESTful JSON architecture.

This project aims to provide that HTTP+JSON interface to your gRPC service. A small amount of configuration in your service to attach HTTP semantics is all that's needed to generate a reverse-proxy with this library.

Installation

The grpc-gateway requires a local installation of the Google protocol buffers compiler protoc v3.0.0 or above. Please install this via your local package manager or by downloading one of the releases from the official repository:

https://github.com/protocolbuffers/protobuf/releases

Then use go get -u to download the following packages:

go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
go get -u github.com/golang/protobuf/protoc-gen-go

This will place three binaries in your $GOBIN;

  • protoc-gen-grpc-gateway
  • protoc-gen-swagger
  • protoc-gen-go

Make sure that your $GOBIN is in your $PATH.

Usage

  1. Define your gRPC service using protocol buffers

    your_service.proto:

    syntax = "proto3";
    package example;
    message StringMessage {
      string value = 1;
    }
    
    service YourService {
      rpc Echo(StringMessage) returns (StringMessage) {}
    }
  2. Add a google.api.http annotation to your .proto file

    your_service.proto:

     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: "*"
    +    };
    +  }
     }

    If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external gRPC Service Configuration file. Check our documentation for more information.

  3. Generate gRPC stub

    The following generates gRPC code for Golang based on path/to/your_service.proto:

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --go_out=plugins=grpc:. \
      path/to/your_service.proto

    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 other programming languages.

    For example, the following generates gRPC code for Ruby based on path/to/your_service.proto:

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --ruby_out=. \
      path/to/your_service.proto
    
    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --plugin=protoc-gen-grpc=grpc_ruby_plugin \
      --grpc-ruby_out=. \
      path/to/your_service.proto
    1. Add the googleapis-common-protos gem (or your language equivalent) as a dependency to your project.
    2. Implement your gRPC service stubs
  5. Generate reverse-proxy using protoc-gen-grpc-gateway

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --grpc-gateway_out=logtostderr=true:. \
      path/to/your_service.proto

    It will generate a reverse proxy path/to/your_service.pb.gw.go.

  6. Write an entrypoint for the HTTP reverse-proxy server

    package main
    
    import (
      "context"  // Use "golang.org/x/net/context" for Golang version <= 1.6
      "flag"
      "net/http"
    
      "github.com/golang/glog"
      "github.com/grpc-ecosystem/grpc-gateway/runtime"
      "google.golang.org/grpc"
    
      gw "path/to/your_service_package"  // Update
    )
    
    var (
      // command-line options:
      // gRPC server endpoint
      grpcServerEndpoint = flag.String("grpc-server-endpoint",  "localhost:9090", "gRPC server endpoint")
    )
    
    func run() error {
      ctx := context.Background()
      ctx, cancel := context.WithCancel(ctx)
      defer cancel()
    
      // Register gRPC server endpoint
      // Note: Make sure the gRPC server is running properly and accessible
      mux := runtime.NewServeMux()
      opts := []grpc.DialOption{grpc.WithInsecure()}
      err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux,  *grpcServerEndpoint, opts)
      if err != nil {
        return err
      }
    
      // Start HTTP server (and proxy calls to gRPC server endpoint)
      return http.ListenAndServe(":8081", mux)
    }
    
    func main() {
      flag.Parse()
      defer glog.Flush()
    
      if err := run(); err != nil {
        glog.Fatal(err)
      }
    }
  7. (Optional) Generate swagger definitions using protoc-gen-swagger

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --swagger_out=logtostderr=true:. \
      path/to/your_service.proto

Parameters and flags

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

In addition we also support the request_context parameter in order to use the http.Request's Context (only for Go 1.7 and above). This parameter can be useful to pass request scoped context between the gateway and the gRPC service.

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.

  • proto/examplepb/echo_service.proto, proto/examplepb/a_bit_of_everything.proto, proto/examplepb/unannotated_echo_service.proto: service definition
    • proto/examplepb/echo_service.pb.go, proto/examplepb/a_bit_of_everything.pb.go, proto/examplepb/unannotated_echo_service.pb.go: [generated] stub of the service
    • proto/examplepb/echo_service.pb.gw.go, proto/examplepb/a_bit_of_everything.pb.gw.go, proto/examplepb/uannotated_echo_service.pb.gw.go: [generated] reverse proxy for the service
    • proto/examplepb/unannotated_echo_service.yaml: gRPC API Configuration for unannotated_echo_service.proto
  • 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 example by CoreOS (and its accompanying blog post).

Features

Supported

  • Generating JSON API handlers.
  • Method parameters in request body.
  • Method parameters in request path.
  • Method parameters in query string.
  • Enum fields in path parameter (including repeated enum fields).
  • Mapping streaming APIs to newline-delimited JSON streams.
  • Mapping HTTP headers with Grpc-Metadata- prefix to gRPC metadata (prefixed with grpcgateway-)
  • Optionally emitting API definitions for OpenAPI (Swagger) v2.
  • Setting gRPC timeouts through inbound HTTP Grpc-Timeout header.
  • Partial support for gRPC API Configuration files as an alternative to annotation.
  • Automatically translating PATCH requests into Field Mask gRPC requests. See the docs for more information.

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.

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 Permanent HTTP header keys (as specified by the IANA here are prefixed with grpcgateway- and added with their values to gRPC request header.
  • HTTP headers that start with 'Grpc-Metadata-' are mapped to gRPC metadata (prefixed with grpcgateway-).
  • While configurable, the default {un,}marshaling uses jsonpb with OrigName: true.

Contribution

See CONTRIBUTING.md.

License

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

You can’t perform that action at this time.