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

9.8K Stars 1.3K Forks BSD 3-Clause "New" or "Revised" License 1.3K Commits 96 Opened issues


gRPC to JSON proxy generator following the gRPC HTTP spec

Services available


Need anything else?

Contributors list

No Data


circleci codecov slack license release stars

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

annotations in your service definitions.

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


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

Check out our documentation!


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.


The grpc-gateway requires a local installation of the Google protocol buffers compiler

v3.0.0 or above. Please install this via your local package manager or by downloading one of the releases from the official repository:

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 ( _ "" _ "" _ "" _ "" )


go mod tidy
to resolve the versions. Install by running
$ go install \ \ \ \

This will place four binaries in your

  • protoc-gen-grpc-gateway
  • protoc-gen-openapiv2
  • protoc-gen-go
  • protoc-gen-go-grpc

Make sure that your

is in your


  1. Define your gRPC service using protocol buffers

    syntax = "proto3";
    package your.service.v1;
    option go_package = "";
    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 of what a

command might look like to generate Go stubs:
   protoc -I . \
      --go_out ./gen/go/ --go_opt paths=source_relative \
      --go-grpc_out ./gen/go/ --go-grpc_opt paths=source_relative \
  1. 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

   protoc -I . --ruby_out ./gen/ruby your/service/v1/your_service.proto

protoc -I . --grpc-ruby_out ./gen/ruby your/service/v1/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

    1. Generate reverse-proxy using

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
      file, but will not allow setting HTTP paths, request parameters or similar
  • additional
    modifications to use a custom mapping
    • relies on parameters in the
      file to set custom HTTP mappings
  • no
    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

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

Here's what a

execution might look like with this option enabled:
      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 \
  1. With custom annotations

Add a

annotation to your .proto file

    syntax = "proto3";
    package your.service.v1;
    option go_package = "";
   +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

compiler. They are included in this repo under the
folder, and we recommend copying them into your
generation file structure. If you've structured your proto files according to something like the Buf style guide, you could copy the files into a top-level

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

Here's what a

execution might look like:
      protoc -I . --grpc-gateway_out ./gen/go \
        --grpc-gateway_opt logtostderr=true \
        --grpc-gateway_opt paths=source_relative \
  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.

Here's what a

execution might look like with this option enabled:
      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 \
  1. Write an entrypoint for the HTTP reverse-proxy server
   package main

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


 gw ""  // 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 {


  1. (Optional) Generate OpenAPI definitions using
   protoc -I . --openapiv2_out ./gen/openapiv2 --openapiv2_opt logtostderr=true your/service/v1/your_service.proto

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

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:

gRPC-Gateway presentation

Parameters and flags

During code generation with

, flags to grpc-gateway tools must be passed through protoc using one of 2 patterns:
  • as part of the
  • using additional
--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

supports custom mapping from Protobuf
to Golang import paths. They are compatible with the parameters with the same names in

In addition we also support the

parameter in order to use the
's Context (only for Go 1.7 and above). This parameter can be useful to pass the request-scoped context between the gateway and the gRPC service.

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.


supports command-line flags to control OpenAPI output (for example,
to output JSON names for fields instead of protobuf names). Run
protoc-gen-openapiv2 --help
for more flag details. Further OpenAPI customization is possible by annotating your
files with options from openapiv2.proto - see abitof_everything.proto for examples.

More Examples

More examples are available under

  • proto/examplepb/echo_service.proto
    : service definition
    • proto/examplepb/echo_service.pb.go
      : [generated] stub of the service
    • proto/examplepb/
      : [generated] reverse proxy for the service
    • proto/examplepb/unannotated_echo_service.yaml
      : gRPC API Configuration for
  • 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

), gRPC-gateway, and a gRPC server, see this example by CoreOS (and its accompanying blog post).



  • Generating JSON API handlers.
  • Method parameters in the request body.
  • Method parameters in the request path.
  • Method parameters in query string.
  • Enum fields in the path parameter (including repeated enum fields).
  • Mapping streaming APIs to newline-delimited JSON streams.
  • Mapping HTTP headers with
    prefix to gRPC metadata (prefixed with
  • Optionally emitting API definitions for OpenAPI (Swagger) v2.
  • Setting gRPC timeouts through inbound HTTP
  • 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
    gRPC request header.
  • HTTP request host is added as
    gRPC request header.
  • HTTP
    header is added as
    gRPC request header.
  • Remaining Permanent HTTP header keys (as specified by the IANA here are prefixed with
    and added with their values to gRPC request header.
  • HTTP headers that start with 'Grpc-Metadata-' are mapped to gRPC metadata (prefixed with
  • While configurable, the default {un,}marshaling uses jsonpb with
    OrigName: true




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.