Need help with grpc-gateway?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

grpc-ecosystem
10.7K Stars 1.4K Forks BSD 3-Clause "New" or "Revised" License 1.5K Commits 104 Opened issues

Description

gRPC to JSON proxy generator following the gRPC HTTP spec

Services available

!
?

Need anything else?

Contributors list

gRPC-Gateway

gRPC to JSON proxy generator following the gRPC HTTP spec

About

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.

Docs

You can read our docs at:

  • https://grpc-ecosystem.github.io/grpc-gateway/

Testimonials

We use the gRPC-Gateway to serve millions of API requests per day, and have been since 2018 and through all of that, we have never had any issues with it.

- William Mill, Ad Hoc

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 backward-compatibility, supporting languages or clients that are 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 following instructions assume you are using Go Modules for dependency management. Use a tool dependency to track the versions of the following executable packages:

// +build tools

package tools

import ( _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway" _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2" _ "google.golang.org/grpc/cmd/protoc-gen-go-grpc" _ "google.golang.org/protobuf/cmd/protoc-gen-go" )

Run

go mod tidy
to resolve the versions. Install by running
$ go install \
    github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \
    github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \
    google.golang.org/protobuf/cmd/protoc-gen-go \
    google.golang.org/grpc/cmd/protoc-gen-go-grpc

This will place four binaries in your

$GOBIN
;
  • protoc-gen-grpc-gateway
  • protoc-gen-openapiv2
  • protoc-gen-go
  • protoc-gen-go-grpc

Make sure that your

$GOBIN
is in your
$PATH
.

Usage

  1. Define your gRPC service using protocol buffers

your_service.proto
:
    syntax = "proto3";
    package your.service.v1;
    option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";

message StringMessage {
  string value = 1;
}

service YourService {
  rpc Echo(StringMessage) returns (StringMessage) {}
}

  1. Generate gRPC stubs

This step generates the gRPC stubs that you can use to implement the service and consume from clients:

Here's an example

buf.gen.yaml
you can use to generate the stubs with buf:
   version: v1beta1
   plugins:
     - name: go
       out: gen/go
       opt:
         - paths=source_relative
     - name: go-grpc
       out: gen/go
       opt:
         - paths=source_relative

With this file in place, you can generate your files using

buf generate
.

For a complete example of using

buf generate
to generate protobuf stubs, see the boilerplate repo. For more information on generating the stubs with buf, see the official documentation.

If you are using

protoc
to generate stubs, here's an example of what a command might look like:
   protoc -I . \
       --go_out ./gen/go/ --go_opt paths=source_relative \
       --go-grpc_out ./gen/go/ --go-grpc_opt paths=source_relative \
       your/service/v1/your_service.proto
  1. Implement your service in gRPC as usual.

  2. Generate reverse-proxy using

    protoc-gen-grpc-gateway

At this point, you have 3 options:

  • no further modifications, use the default mapping to HTTP semantics (method, path, etc.)
    • this will work on any
      .proto
      file, but will not allow setting HTTP paths, request parameters or similar
  • additional
    .proto
    modifications to use a custom mapping
    • relies on parameters in the
      .proto
      file to set custom HTTP mappings
  • no
    .proto
    modifications, but use an external configuration file
    • relies on an external configuration file to set custom HTTP mappings
    • mostly useful when the source proto file isn't under your control
  1. Using the default mapping

This requires no additional modification to the

.proto
file but does require enabling a specific option when executing the plugin. The
generate_unbound_methods
should be enabled.

Here's what a

buf.gen.yaml
file might look like with this option enabled:
   version: v1beta1
   plugins:
     - name: go
       out: gen/go
       opt:
         - paths=source_relative
     - name: go-grpc
       out: gen/go
       opt:
         - paths=source_relative
     - name: grpc-gateway
       out: gen/go
       opt:
         - paths=source_relative
         - generate_unbound_methods=true

With

protoc
(just the grpc-gateway stubs):
   protoc -I . --grpc-gateway_out ./gen/go \
       --grpc-gateway_opt logtostderr=true \
       --grpc-gateway_opt paths=source_relative \
       --grpc-gateway_opt generate_unbound_methods=true \
       your/service/v1/your_service.proto
  1. With custom annotations

Add a

google.api.http
annotation to your .proto file

your_service.proto
:
    syntax = "proto3";
    package your.service.v1;
    option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";
   +
   +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: "*"
  • };
  • } }

You will need to provide the required third party protobuf files to the protobuf compiler. If you are using buf, this dependency can be added to the

deps
array in your
buf.yaml
under the name
buf.build/beta/googleapis
:
yaml
version: v1beta1
name: buf.build/yourorg/myprotos
deps:

  • buf.build/beta/googleapis
Always run
buf beta mod update
after adding a dependency to your
buf.yaml
.

See abitof_everything.proto for examples of more annotations you can add to customize gateway behavior and generated OpenAPI output.

Here's what a

buf.gen.yaml
file might look like:
   version: v1beta1
   plugins:
     - name: go
       out: gen/go
       opt:
         - paths=source_relative
     - name: go-grpc
       out: gen/go
       opt:
         - paths=source_relative
     - name: grpc-gateway
       out: gen/go
       opt:
         - paths=source_relative

If you are using

protoc
to generate stubs, you need to ensure the required dependencies are available to the compiler at compile time. These can be found by manually cloning and copying the relevant files from the googleapis repository, and providing them to
protoc
when running. The files you will need are:
   google/api/annotations.proto
   google/api/field_behaviour.proto
   google/api/http.proto
   google/api/httpbody.proto

Here's what a

protoc
execution might look like:
   protoc -I . --grpc-gateway_out ./gen/go \
       --grpc-gateway_opt logtostderr=true \
       --grpc-gateway_opt paths=source_relative \
       your/service/v1/your_service.proto
  1. External configuration If you do not want to (or cannot) 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. This is best combined with the
    standalone=true
    option to generate a file that can live in its own package, separate from the files generated by the source protobuf file.

Here's what a

buf.gen.yaml
file might look like with this option enabled:
   version: v1beta1
   plugins:
     - name: go
       out: gen/go
       opt:
         - paths=source_relative
     - name: go-grpc
       out: gen/go
       opt:
         - paths=source_relative
     - name: grpc-gateway
       out: gen/go
       opt:
         - paths=source_relative
         - grpc_api_configuration=path/to/config.yaml
         - standalone=true

With

protoc
(just the grpc-gateway stubs):
   protoc -I . --grpc-gateway_out ./gen/go \
       --grpc-gateway_opt logtostderr=true \
       --grpc-gateway_opt paths=source_relative \
       --grpc-gateway_opt grpc_api_configuration=path/to/config.yaml \
       --grpc-gateway_opt standalone=true \
       your/service/v1/your_service.proto
  1. Write an entrypoint for the HTTP reverse-proxy server
   package main

import ( "context" "flag" "net/http"

 "github.com/golang/glog"
 "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
 "google.golang.org/grpc"

 gw "github.com/yourorg/yourrepo/proto/gen/go/your/service/v1/your_service"  // 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)
 }

}

  1. (Optional) Generate OpenAPI definitions using
    protoc-gen-openapiv2

Here's what a

buf.gen.yaml
file might look like:
   version: v1beta1
   plugins:
     - name: go
       out: gen/go
       opt:
         - paths=source_relative
     - name: go-grpc
       out: gen/go
       opt:
         - paths=source_relative
     - name: grpc-gateway
       out: gen/go
       opt:
         - paths=source_relative
     - name: openapiv2
       out: gen/openapiv2

To use the custom protobuf annotations supported by

protoc-gen-openapiv2
, we need another dependency added to our protobuf generation step. If you are using
buf
, you can add the
buf.build/grpc-ecosystem/grpc-gateway
dependency to your
deps
array:
yaml
   version: v1beta1
   name: buf.build/yourorg/myprotos
   deps:
     - buf.build/beta/googleapis
     - buf.build/grpc-ecosystem/grpc-gateway

With

protoc
(just the swagger file):
   protoc -I . --openapiv2_out ./gen/openapiv2 \
       --openapiv2_opt logtostderr=true \
       your/service/v1/your_service.proto

If you are using

protoc
to generate stubs, you will need to copy the protobuf files from the
protoc-gen-openapiv2/options
directory of this repository, and providing them to
protoc
when running.

Note that this plugin also supports generating OpenAPI definitions for unannotated methods; use the

generate_unbound_methods
option to enable this.

Video intro

This GopherCon UK 2019 presentation from our maintainer @JohanBrandhorst provides a good intro to using the gRPC-Gateway. It uses the following boilerplate repo as a base: https://github.com/johanbrandhorst/grpc-gateway-boilerplate.

Parameters and flags

When using

buf
to generate stubs, flags and parameters are passed through the
opt
field in your
buf.gen.yaml
file, for example:
version: v1beta1
plugins:
  - name: grpc-gateway
    out: gen/go
    opt:
      - paths=source_relative
      - grpc_api_configuration=path/to/config.yaml
      - standalone=true

During code generation with

protoc
, flags to gRPC-Gateway tools must be passed through
protoc
using one of 2 patterns:
  • as part of the
    --_out
    protoc
    parameter:
    --_out=:
--grpc-gateway_out=logtostderr=true,repeated_path_param_separator=ssv:.
--openapiv2_out=logtostderr=true,repeated_path_param_separator=ssv:.
  • using additional
    --_opt
    parameters:
    --_opt=[,]*
--grpc-gateway_opt logtostderr=true,repeated_path_param_separator=ssv
# or separately
--grpc-gateway_opt logtostderr=true --grpc-gateway_opt repeated_path_param_separator=ssv
--openapiv2_opt logtostderr=true,repeated_path_param_separator=ssv
# or separately
--openapiv2_opt logtostderr=true --openapiv2_opt repeated_path_param_separator=ssv

More examples

More examples are available under the

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 the request body.
  • Method parameters in the request path.
  • Method parameters in the query string.
  • Enum fields in the 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 patches are 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 protojson.

Contribution

See CONTRIBUTING.md.

License

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.