grpc-gateway — RESTful JSON API Proxy for gRPC Services

Introduction

grpc-gateway bridges the gap between gRPC microservices and RESTful clients. By reading gRPC service definitions annotated with HTTP mapping rules, it generates a reverse proxy server that accepts JSON/HTTP requests, translates them into gRPC calls, and returns JSON responses. This lets teams adopt gRPC internally while exposing familiar REST APIs externally.

What grpc-gateway Does

• Generates a reverse proxy from annotated Protocol Buffer service definitions
• Translates HTTP/JSON requests to gRPC and responses back to JSON
• Produces OpenAPI (Swagger) specifications automatically from your protos
• Supports path parameters, query parameters, and request body mappings
• Handles streaming RPCs with server-sent events or chunked transfer

Architecture Overview

The gateway works as a protoc plugin that reads google.api.http annotations in your .proto files. At build time, it generates Go code implementing an HTTP handler that marshals JSON to protobuf, calls the gRPC backend, and marshals the protobuf response back to JSON. At runtime, this handler runs as a standard Go HTTP server (often alongside the gRPC server in the same binary) or as a standalone reverse proxy process.

Self-Hosting & Configuration

• Install protoc plugins: protoc-gen-grpc-gateway and protoc-gen-openapiv2
• Add google/api/annotations.proto to your proto imports
• Annotate RPCs with option (google.api.http) = { get: "/v1/resource/{id}" };
• Run protoc to generate the gateway Go code
• Register the generated handler on an HTTP mux and start the server

Key Features

• Single source of truth: proto files define both gRPC and REST interfaces
• Automatic OpenAPI spec generation for documentation and client code generation
• Customizable JSON marshaling with support for field masks and enum strings
• Request routing supports path parameters, query strings, and nested message bodies
• Middleware support via standard Go HTTP handler chaining

Comparison with Similar Tools

• Envoy gRPC-JSON transcoding — proxy-level transcoding without code generation; grpc-gateway embeds in your Go binary
• gRPC-Web — browser gRPC client over HTTP/1.1; grpc-gateway provides full REST with custom URL paths
• Connect (connectrpc) — unified protocol supporting gRPC and REST; grpc-gateway works with existing gRPC services
• Twirp — simple RPC framework with JSON support; grpc-gateway preserves full gRPC compatibility
• Kong/APISIX gRPC plugins — API gateway transcoding; grpc-gateway generates a dedicated Go server

FAQ

Q: Do I need a separate process for the gateway? A: No. You can run the gateway handler in the same Go binary as your gRPC server on a different port.

Q: Does it support gRPC streaming? A: Server-side streaming is supported. Client-side and bidirectional streaming have limited HTTP mapping support.

Q: Can I customize the JSON output format? A: Yes. The runtime package offers options for enum representation, field naming, and empty field emission.

Q: How do I add authentication? A: Use standard HTTP middleware (JWT validation, API keys) in front of the gateway handler.

Sources

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