github.com/grpc-ecosystem/grpc-gateway/v2
gRPC to JSON proxy generator following the gRPC HTTP spec
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.
You can read our docs at:
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
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 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-gatewayprotoc-gen-openapiv2protoc-gen-goprotoc-gen-go-grpcMake sure that your $GOBIN is in your $PATH.
You may alternatively download the binaries from the GitHub releases page. We generate SLSA3 signatures using the OpenSSF's slsa-framework/slsa-github-generator during the release process. To verify a release binary:
attestation.intoto.jsonl from the GitHub releases page.slsa-verifier -artifact-path <the-binary> -provenance attestation.intoto.jsonl -source github.com/grpc-ecosystem/grpc-gateway -tag <the-tag>
Alternatively, see the section on remotely managed plugin versions below.
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) {}
}
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: v1
plugins:
- plugin: go
out: gen/go
opt:
- paths=source_relative
- plugin: 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 generateto 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
protoc-gen-grpc-gatewayAt this point, you have 3 options:
.proto file, but will not allow setting HTTP paths, request parameters or similar.proto modifications to use a custom mapping
.proto file to set custom HTTP mappings.proto modifications, but use an external configuration file
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: v1
plugins:
- plugin: go
out: gen/go
opt:
- paths=source_relative
- plugin: go-grpc
out: gen/go
opt:
- paths=source_relative
- plugin: 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 paths=source_relative \
--grpc-gateway_opt generate_unbound_methods=true \
your/service/v1/your_service.proto
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
depsarray in yourbuf.yamlunder the namebuf.build/googleapis/googleapis:version: v1 name: buf.build/yourorg/myprotos deps: - buf.build/googleapis/googleapisAlways run
buf mod updateafter adding a dependency to yourbuf.yaml.
See a_bit_of_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: v1
plugins:
- plugin: go
out: gen/go
opt:
- paths=source_relative
- plugin: go-grpc
out: gen/go
opt:
- paths=source_relative
- plugin: 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_behavior.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 paths=source_relative \
your/service/v1/your_service.proto
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: v1
plugins:
- plugin: go
out: gen/go
opt:
- paths=source_relative
- plugin: go-grpc
out: gen/go
opt:
- paths=source_relative
- plugin: 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 paths=source_relative \
--grpc-gateway_opt grpc_api_configuration=path/to/config.yaml \
--grpc-gateway_opt standalone=true \
your/service/v1/your_service.proto
package main
import (
"context"
"flag"
"net/http"
"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"google.golang.org/grpc/grpclog"
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.WithTransportCredentials(insecure.NewCredentials())}
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()
if err := run(); err != nil {
grpclog.Fatal(err)
}
}
protoc-gen-openapiv2Here's what a buf.gen.yaml file might look like:
version: v1
plugins:
- plugin: go
out: gen/go
opt:
- paths=source_relative
- plugin: go-grpc
out: gen/go
opt:
- paths=source_relative
- plugin: grpc-gateway
out: gen/go
opt:
- paths=source_relative
- plugin: 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:
version: v1
name: buf.build/yourorg/myprotos
deps:
- buf.build/googleapis/googleapis
- buf.build/grpc-ecosystem/grpc-gateway
With protoc (just the swagger file):
protoc -I . --openapiv2_out ./gen/openapiv2 \
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.
It is possible with the HTTP mapping for a gRPC service method to create duplicate mappings with the only difference being constraints on the path parameter.
/v1/{name=projects/*} and /v1/{name=organizations/*} both become /v1/{name}. When
this occurs the plugin will rename the path parameter with a "_1" (or "_2" etc) suffix
to differentiate the different operations. So in the above example, the 2nd path would become
/v1/{name_1=organizations/*}. This can also cause OpenAPI clients to URL encode the "/" that is
part of the path parameter as that is what OpenAPI defines in the specification. To allow gRPC gateway to
accept the URL encoded slash and still route the request, use the UnescapingModeAllCharacters or
UnescapingModeLegacy (which is the default currently though may change in future versions). See
Customizing Your Gateway
for more information.
As an alternative to all of the above, you can use buf with
remote plugins
to manage plugin versions and generation. An example buf.gen.yaml using remote
plugin generation looks like this:
version: v1
plugins:
- plugin: buf.build/protocolbuffers/go:v1.31.0
out: gen/go
opt:
- paths=source_relative
- plugin: buf.build/grpc/go:v1.3.0
out: gen/go
opt:
- paths=source_relative
- plugin: buf.build/grpc-ecosystem/gateway:v2.16.2
out: gen/go
opt:
- paths=source_relative
- plugin: buf.build/grpc-ecosystem/openapiv2:v2.16.2
out: gen/openapiv2
This requires no local installation of any plugins. Be careful to use the same
version of the generator as the runtime library, i.e. if using v2.16.2, run
$ go get github.com/grpc-ecosystem/grpc-gateway/v2@v2.16.2
To get the same version of the runtime in your go.mod.
Note that usage of remote plugins is incompatible with usage of external configuration files like grpc_api_configuration.
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.
When using buf to generate stubs, flags and parameters are passed through
the opt field in your buf.gen.yaml file, for example:
version: v1
plugins:
- plugin: 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:
--<tool_suffix>_out protoc parameter: --<tool_suffix>_out=<flags>:<path>--grpc-gateway_out=repeated_path_param_separator=ssv:.
--openapiv2_out=repeated_path_param_separator=ssv:.
--<tool_suffix>_opt parameters: --<tool_suffix>_opt=<flag>[,<flag>]*--grpc-gateway_opt repeated_path_param_separator=ssv
--openapiv2_opt repeated_path_param_separator=ssv
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 serviceproto/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 serviceproto/examplepb/unannotated_echo_service.yaml: gRPC API Configuration for unannotated_echo_service.protoserver/main.go: service implementationmain.go: entrypoint of the generated reverse proxyTo 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).
This example by neiro.ai (and its accompanying blog post) shows how mediafiles using multipart/form-data can be integrated into rpc messages using a middleware.
Grpc-Metadata- prefix to gRPC metadata (prefixed with grpcgateway-)Grpc-Timeout header.But patches are welcome.
X-Forwarded-For gRPC request header.X-Forwarded-Host gRPC request header.Authorization header is added as authorization gRPC request header.grpcgateway- and added with their values to gRPC request
header.grpcgateway-)./api/v1/{name=projects/*/topics/*} or /prefix/{path=organizations/**}.See CONTRIBUTING.md.
gRPC-Gateway is licensed under the BSD 3-Clause License. See LICENSE for more details.
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.