gRPC documentation is thorough on the protocol’s features and sparse on the operational realities of running it at production scale. The gap between the getting-started experience and the production experience is wide enough to have surprised most of the teams that have made the journey. The surprises are not fatal. They are the kind that would have been useful to know before the architecture decision was made.

The gRPC pitch is compelling: Protocol Buffers serialization that is faster and smaller than JSON, HTTP/2 multiplexing that reduces connection overhead, generated client and server stubs that eliminate serialization bugs, strong typing that catches integration errors at compile time rather than runtime. All of these benefits are real. All of them come with operational requirements that the pitch does not emphasize.

The choice between REST, GraphQL, and gRPC is treated in most discussions as a question of technical preference when it is primarily a question of context. Each protocol was designed for a specific problem space. Each performs well in that space and poorly outside it. The comparison articles that declare one winner across all use cases are either selling something or have not operated all three at production scale.

REST’s dominance in public API design is not accidental. The constraints it imposes — statelessness, uniform interface, resource-based addressing — map naturally to HTTP’s caching infrastructure, client library ecosystems, and the mental model that most developers already carry from web development. A REST API can be consumed with curl. It can be documented with OpenAPI. It can be cached at the edge. These properties have real operational value that architectural elegance alone cannot purchase.