Clever/grpc-gateway

Name: grpc-gateway

Owner: Clever

Description: gRPC to JSON proxy generator

Created: 2016-07-22 16:51:20.0

Updated: 2016-07-22 16:51:22.0

Pushed: 2016-07-25 18:34:52.0

Homepage: null

Size: 729

Language: Go

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

grpc-gateway

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.

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

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 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.

Installation

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

r tmp
mp
clone https://github.com/google/protobuf
rotobuf
togen.sh
nfigure

 check
 make install

Then, go get -u as usual.

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

Usage

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

1. Define your service in gRPC

   your_service.proto:

   ax = "proto3";
   age example;
   age StringMessage {
   ing value = 1;
   
   
   ice YourService {
    Echo(StringMessage) returns (StringMessage) {}
   
   

2. Add a custom option to the .proto file

   your_service.proto:

   ax = "proto3";
   age example;
   
   ort "google/api/annotations.proto";
   
   age StringMessage {
   ring value = 1;
   
   
   ice YourService {
   

3. rpc Echo(StringMessage) returns (StringMessage) {}

4. rpc Echo(StringMessage) returns (StringMessage) {

5. option (google.api.http) = {

6.  post: "/v1/example/echo"
   

7.  body: "*"
   

8. };

9. } }

10. Generate gRPC stub

    oc -I/usr/local/include -I. \
    GOPATH/src \
    GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    o_out=Mgoogle/api/annotations.proto=github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis/google/api,plugins=grpc:. \
    h/to/your_service.proto
    

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

11. Implement your service in gRPC as usual

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

    e.g.

    toc -I/usr/local/include -I. \
    I$GOPATH/src \
    I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    -ruby_out=. \
    ath/to/your/service_proto
    
    toc -I/usr/local/include -I. \
    I$GOPATH/src \
    I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    -plugin=protoc-gen-grpc-ruby=grpc_ruby_plugin \
    -grpc-ruby_out=. \
    ath/to/your/service.proto
    

13. Implement your service

14. Generate reverse-proxy

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

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

15. Write an entrypoint

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

    age main
    rt (
    ag"
    t/http"
    
    thub.com/golang/glog"
    lang.org/x/net/context"
    thub.com/grpc-ecosystem/grpc-gateway/runtime"
    ogle.golang.org/grpc"
    
    "path/to/your_service_package"
    
    
    (
    oEndpoint = flag.String("echo_endpoint", "localhost:9090", "endpoint of YourService")
    
    
     run() error {
     := context.Background()
    , cancel := context.WithCancel(ctx)
    er cancel()
    
     := runtime.NewServeMux()
    s := []grpc.DialOption{grpc.WithInsecure()}
     := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *echoEndpoint, opts)
    err != nil {
    eturn err
    
    
    p.ListenAndServe(":8080", mux)
    urn nil
    
    
     main() {
    g.Parse()
    er glog.Flush()
    
    err := run(); err != nil {
    log.Fatal(err)
    
    
    

16. (Optional) Generate swagger definitions

    oc -I/usr/local/include -I. \
    GOPATH/src \
    GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    wagger_out=logtostderr=true:. \
    h/to/your_service.proto
    

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/echo_service.pb.gw.go, examplepb/a_bit_of_everything.pb.gw.go: [generated] reverse proxy for the service
• server/main.go: service implementation
• main.go: entrypoint of the generated reverse proxy

Features

Supported

• 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?)

License

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