gRPC
gRPC is a high-performance RPC framework using HTTP/2 and Protocol Buffers, with generated clients, streaming calls, deadlines, and typed errors across languages.
Definition
gRPC is an open-source remote procedure call framework that defines services in Protocol Buffers, generates typed client and server stubs, and runs over HTTP/2 with unary and streaming calls.
Context and scope
Use gRPC for internal service-to-service calls, polyglot systems, and streaming workloads where a typed contract and efficient binary encoding matter.
Common misconceptions
- gRPC is always faster; payload efficiency helps, but latency still depends on connection reuse, distance, and workload
- Browsers call gRPC services directly; native gRPC needs HTTP/2 framing browsers do not expose, so gRPC-Web needs a proxy
- Protobuf schema changes are always safe; field numbers and types still follow compatibility rules
Anti-patterns
- Copying mutable .proto files between repositories instead of versioning them in a registry
- Ignoring deadlines so one slow dependency consumes every worker
- Assuming REST status and retry semantics map one-to-one onto gRPC codes
Related concepts
Related examples
Authoritative source
How it works
A service is declared in a .proto file. The compiler generates client and server code in each target language, so callers invoke methods with typed objects rather than constructing URLs and parsing JSON by hand. gRPC runs over HTTP/2, which provides multiplexed streams, flow control, and header compression.
service Orders {
rpc GetOrder(GetOrderRequest) returns (Order);
rpc WatchOrders(WatchRequest) returns (stream OrderEvent);
}Four call shapes exist: unary, server streaming, client streaming, and bidirectional streaming. Deadlines propagate from caller to callee, and failures use a small set of status codes such as UNAVAILABLE, DEADLINE_EXCEEDED, and INVALID_ARGUMENT.
When to use it
gRPC shines between backend services owned by different teams or written in different languages, and for streaming large datasets, telemetry, or event feeds. It is also a good fit when a schema registry and code generation already govern your contracts. Public browser-facing APIs usually prefer REST or GraphQL because tooling, caching, and debugging are simpler.
Trade-offs
Binary payloads are compact but harder to inspect; grpcurl and reflection help. Generated code is convenient but couples releases to schema changes, so compatibility rules and a registry are required. Proxies and load balancers must understand HTTP/2 trailers and long-lived streams. Retries are not automatic and should respect idempotency.
Example and misconceptions
A team migrating from JSON often expects gRPC to fix latency. In practice, connection reuse and deadline discipline deliver more than encoding alone. A single unary call that opens a fresh connection per request can be slower than a warm REST client.
Related concepts: REST vs RPC, Connection Pooling, and Timeout Budget.