grpc-gateway
Go plugin for protoc that generates a reverse-proxy server translating RESTful JSON API calls into gRPC calls. Add HTTP annotations to .proto files and grpc-gateway generates a REST endpoint that proxies to the gRPC service. Also generates OpenAPI 2.0/3.0 docs. Used when you need both gRPC (for microservice-to-microservice) and REST (for public APIs, browsers) from the same service definition.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
TLS configuration inherited from gRPC server. Authentication interceptors apply to both gRPC and REST via the proxy. CORS must be configured separately on the HTTP server.
⚡ Reliability
Best When
You have existing gRPC services that need to be exposed as REST APIs for external clients or browsers without maintaining a separate REST implementation.
Avoid When
You don't use gRPC, or your REST API has semantics that can't be expressed with protobuf HTTP annotations.
Use Cases
- • Expose gRPC services as REST APIs for browser clients and external consumers without writing two separate service implementations
- • Generate OpenAPI documentation automatically from protobuf service definitions with grpc-gateway's swagger plugin
- • Support both gRPC and REST protocols from the same Go service by running grpc-gateway alongside the gRPC server
- • Enable agent systems to call internal gRPC microservices via REST without requiring gRPC client setup
- • Implement HTTP/JSON → gRPC transcoding for mobile and web clients that can't use gRPC directly
Not For
- • Services that only need REST — plain HTTP frameworks (gin, chi, echo) are simpler without gRPC overhead
- • Teams not using protobuf/gRPC — grpc-gateway requires proto definitions as the source of truth
- • Complex REST APIs with fine-grained HTTP semantics — protobuf HTTP annotations can't express all REST patterns
Interface
Authentication
Code generation plugin. Authentication is implemented in the gRPC service's interceptors or grpc-gateway's middleware.
Pricing
BSD license. Part of the grpc-ecosystem organization.
Agent Metadata
Known Gotchas
- ⚠ Proto HTTP annotations (option google.api.http = {get: "/v1/{name=...}"}) require importing google/api/annotations.proto — missing import causes protoc compilation errors
- ⚠ grpc-gateway runs as a separate HTTP server alongside the gRPC server — requires managing two server ports and startup ordering
- ⚠ gRPC metadata is not automatically forwarded as HTTP headers — configure IncomingHeaderMatcher and OutgoingHeaderMatcher for header passthrough
- ⚠ Streaming RPCs (server-streaming, client-streaming) have limited REST support — grpc-gateway can handle server streaming as chunked HTTP but bidirectional streaming is not supported
- ⚠ OpenAPI generation requires protoc-gen-openapiv2 plugin separately from grpc-gateway — version pinning between plugins is important for consistent output
- ⚠ URL path parameters in HTTP annotations must match proto field names — mismatches cause runtime routing failures that are hard to debug
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for grpc-gateway.
Scores are editorial opinions as of 2026-03-06.