Gateways and REST: google.api.http annotations, transcoding limits, gRPC-Web, and the ConnectRPC alternative

Annotations compile into a proxy

Before you write a handcrafted REST adapter for a gRPC service, ask yourself: what happens when the 60th RPC is added? That question is what makes the generated approach worth understanding first.

External consumers will not install protoc. The standard answer keeps gRPC inside and compiles a REST facade from the same contract — google.api.http annotations on each RPC:

import "google/api/annotations.proto";

service Orders {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = { get: "/v1/orders/{order_id}" };
  }
  rpc CreateOrder(CreateOrderRequest) returns (Order) {
    option (google.api.http) = { post: "/v1/orders", body: "*" };
  }
}

The binding rules are mechanical: path template variables like order_id bind to the request message field of the same name; for a GET, every remaining scalar field becomes an accepted query parameter; body: "*" maps the whole JSON body onto the request message for writes. From this, protoc-gen-grpc-gateway generates a reverse proxy — a runtime.ServeMux that is itself just an http.Handler, so everything from the HTTP unit applies: wrap it in middleware, mount it under a path, time it out.

gw := runtime.NewServeMux()
// Dials the gRPC backend; JSON in, protobuf over HTTP/2 out, JSON back.
err := orderspb.RegisterOrdersHandlerFromEndpoint(ctx, gw, "orders:50051", dialOpts)
// The Hook's missing line — never proxy without a budget:
srv := &http.Server{Addr: ":8080", Handler: withTimeout(gw, 5*time.Second)}

Per request the gateway does: decode JSON into the generated request struct, invoke the RPC through a real gRPC client connection (interceptors and client-side balancing included), encode the response back to JSON. There is also an in-process variant — RegisterOrdersHandlerServer — that calls your server implementation directly without dialing; it saves the hop but bypasses client-side interceptors and stats, so most production setups keep the real connection. The same annotations feed protoc-gen-openapiv2, so the public OpenAPI document is generated from the contract instead of drifting away from it.

What refuses to translate: streams, errors, deadlines

Transcoding is honest about unary calls and evasive about everything else. Server streaming technically works: the gateway emits newline-delimited JSON chunks, each wrapped in a result envelope — not a JSON array, which breaks every client that calls response.json() expecting one. Client and bidi streaming do not map to request/response REST at all; if a browser needs them, that endpoint needs a different design — websockets, gRPC-Web, or Connect — not a gateway annotation.

Errors need a translation table because the two worlds disagree about what a status is. The gateway ships a default mapping — InvalidArgument to 400, NotFound to 404, PermissionDenied to 403, Unavailable to 503, DeadlineExceeded to 504, Internal and Unknown to 500 — and emits the google.rpc.Status JSON as the body. The day your public API needs its own error envelope, you install runtime.WithErrorHandler and own the mapping; do it deliberately once, not endpoint by endpoint.

Deadlines are the Hook. REST clients do not send grpc-timeout; they just hang up, and a hung-up HTTP client does not automatically cancel the upstream RPC unless the request context is wired through — and even then, a never-answering backend holds the goroutine until something bounds it. The gateway honors an inbound Grpc-Timeout header if present (it almost never is, from public clients) and supports a default via runtime.DefaultContextTimeout or plain http.Server/middleware timeouts. The rule that would have saved the Hook: a proxy in front of gRPC must originate deadlines, not just forward them, because its public callers never will.

Topology choices: gateway, gRPC-Web, or Connect

The common production topology is now visible end to end: services speak gRPC to each other — compiled contracts, propagated deadlines, streams — and the public edge runs the generated gateway speaking REST and JSON to people you cannot hand a .proto file to. Internal teams get the strict contract; external consumers get curl, OpenAPI docs, and API-key middleware on a plain http.Handler.

Browsers complicate it. Browser fetch cannot read HTTP/2 trailers — and gRPC puts grpc-status precisely there — so native browser gRPC is impossible regardless of HTTP/2 support. gRPC-Web is the workaround protocol: the status moves into the body or headers, and a proxy (Envoy’s grpc_web filter, or the gateway) translates to real gRPC. It works, at the cost of one more moving piece in every browser path.

ConnectRPC is the honest modern alternative to the whole sandwich: one server speaks three protocols on one port — gRPC for existing internal clients, gRPC-Web for browsers without a proxy, and the Connect protocol, where a unary call is a plain HTTP POST with a JSON body you can curl and errors live in the response body, not trailers. Same .proto, different generated runtime. The tradeoff is ecosystem age: grpc-gateway has a decade of production scar tissue, Connect is younger with a smaller tool universe — but for a new Go system that needs browsers and curl-ability, it deletes the gateway and the Envoy filter from the architecture diagram.

Whichever edge you pick, the protobuf-first flow exerts a quiet design pressure worth naming: annotations force you to phrase every operation as a resource path and a verb, with explicit request and response messages. Teams that start REST-first often skip that modeling and grow verb-soup endpoints; teams that compile REST from a contract get resource discipline imposed by the toolchain.