grpc-gateway

grpc-gateway reads protobuf service definitions annotated with google.api.http options and generates a reverse-proxy server that translates a RESTful HTTP+JSON API into gRPC calls. Instead of hand-writing and maintaining a parallel REST API alongside a gRPC service, teams add HTTP annotations to their .proto files and let the generator produce the routing, request decoding, and response marshaling code automatically.

The project ships as a protoc/buf code-generation plugin (protoc-gen-grpc-gateway) alongside a runtime package that the generated code imports for request multiplexing, JSON/protobuf marshaling, error handling, and field-mask support. A companion plugin, protoc-gen-openapiv2, emits Swagger/OpenAPI 2.0 documentation from the same annotations, and an alpha protoc-gen-openapiv3 plugin does the same for OpenAPI 3.1 — so one set of proto definitions can drive gRPC, REST, and API documentation together.

What You Get

• A protoc/buf plugin (protoc-gen-grpc-gateway) that generates a Go reverse-proxy server from google.api.http annotations in .proto files
• A runtime package (ServeMux, marshalers, error handling, field masks) that the generated proxy code depends on at runtime
• protoc-gen-openapiv2 for generating Swagger/OpenAPI 2.0 specs from the same proto annotations
• An alpha protoc-gen-openapiv3 plugin for OpenAPI 3.1 output
• Configurable JSON marshaling (jsonpb-compatible), custom error handlers, and pluggable header/metadata mapping between HTTP and gRPC

Common Use Cases

• Exposing an existing internal gRPC service to external clients (browsers, mobile apps, third-party integrators) as a JSON REST API without duplicating business logic
• Providing backward-compatible REST endpoints while migrating a service to gRPC internally
• Generating OpenAPI/Swagger documentation automatically from proto definitions for API consumers who expect REST tooling
• Building a single API gateway in front of multiple gRPC microservices that also needs to speak HTTP/JSON to edge clients

Under The Hood

Architecture

The project is split into a code generator and a runtime library that the generated code depends on. protoc-gen-grpc-gateway/main.go is a thin protoc/buf plugin entry point that hands the CodeGeneratorRequest to an internal generator package, which walks each proto service’s methods, reads their google.api.http annotations, and emits Go source defining HTTP routes bound to gRPC client calls. At runtime, the generated RegisterXHandler functions register those routes on a runtime.ServeMux (in the runtime package), which is a purpose-built HTTP multiplexer — not net/http.ServeMux — that matches path patterns extracted from the annotations, decodes query/body parameters into protobuf messages via pluggable Marshalers, and forwards the resulting call through a standard gRPC client connection. A parallel protoc-gen-openapiv2/protoc-gen-openapiv3 plugin walks the same annotated proto files through a separate internal generator to emit OpenAPI documents, sharing the annotation-parsing layer but not the runtime request path. This separation — codegen-time route extraction, runtime-time request translation — means the generated proxy has no reflection or annotation parsing cost at request time; everything is resolved to concrete route matching and message construction ahead of time.

Tech Stack

The module (github.com/grpc-ecosystem/grpc-gateway/v2) targets modern Go (go 1.26 in go.mod) and builds on google.golang.org/grpc and google.golang.org/protobuf as its core runtime dependencies, with google.golang.org/genproto for well-known API types. JSON marshaling defaults route through protobuf’s own JSON mapping rules with a jsonpb-compatible Marshaler interface, and the go-openapi family (errors, runtime, strfmt, swag, validate) backs the OpenAPI validation tooling. Observability is first-class: go.opentelemetry.io/otel and its otelgrpc/otelhttp instrumentation packages are direct dependencies, letting generated proxies emit traces across the HTTP-to-gRPC hop out of the box. The repo supports both Go modules and Bazel (BUILD.bazel, WORKSPACE, MODULE.bazel) as build systems, and CI runs through GitHub Actions with Renovate managing dependency updates automatically.

Code Quality

The project carries an extensive test suite (over 50 _test.go files across runtime, the generator internals, and the OpenAPI plugins), including dedicated tests for edge cases like path unescaping modes, field masks, and marshaler registry behavior. go.mod declares honnef.co/go/tools/cmd/staticcheck as a tracked tool dependency, indicating static analysis is part of the standard workflow, and a .github/workflows/ci.yml pipeline runs the suite on every change. Error handling is explicit and typed throughout the runtime package (a dedicated errors.go maps gRPC status codes to HTTP responses rather than relying on generic error strings), and naming conventions follow standard Go idioms (exported ServeMux, Marshaler, HandlerFunc types with doc comments). A CONTRIBUTING.md and Slack community channel support external contributions, and the project has 470+ contributors, suggesting sustained external review pressure on code quality over time.

API Design The public API centers on a small set of well-documented primitives — runtime.NewServeMux, the Marshaler interface, and generated RegisterXHandler(FromEndpoint) functions — that keep the integration surface narrow even though the internal routing logic is substantial. Configuration is done through functional options passed to NewServeMux (for example WithMarshalerOption, WithUnescapingMode, WithErrorHandler), a idiomatic Go pattern that keeps the common case (default JSON marshaling, standard routing) a one-line call while still exposing deep customization for teams with nonstandard requirements. The tradeoff is upfront proto-annotation overhead: getting a working gateway requires learning the google.api.http annotation syntax and running an extra codegen step in the build, which is a real learning curve compared to hand-rolling REST handlers, but it keeps the REST surface mechanically derived from — and impossible to drift from — the gRPC service definition.