What Is gRPC? 7 Things Every Developer Should Know (With Examples)

November 6, 2026 · Web Development

Two services need to talk. One is Go, the other Python, and they exchange thousands of small messages a second. JSON over REST works — until payloads, parsing, and per-request connection setup start to cost real time. What is gRPC, and why do teams reach for it exactly here? This guide answers in 7 parts: definition, the two ingredients, the .proto contract, the four call types, a hand-encoded message, where it shines, and where it does not work.

What is gRPC?

gRPC is an open-source framework for remote procedure calls — calling a function on another machine as if it were local. You define a service once, and gRPC generates the client and server code for you. The name is a recursive acronym for "gRPC Remote Procedure Calls". It grew out of Google's internal Stubby RPC system: in March 2015 Google decided to rebuild Stubby as open source, and gRPC 1.0 shipped in August 2016.

Where a REST API says "here are my URLs, send JSON and hope the shapes match", gRPC says "here is the exact interface, in every language, enforced by generated code" — and that single difference explains most of its strengths and weaknesses.

Illustration of gRPC: one server calling a function on a second server across a network, shown as a single direct line as if the function were local
gRPC's promise: a call to another machine that feels like a call to a local function — the framework handles the network, the bytes, and the types.

The two ingredients: Protocol Buffers and HTTP/2

Protocol Buffers encode a message as tagged fields — a field number, a wire type, and a payload — with no field names on the wire. Small numbers take one byte each (varints); strings carry a length prefix. The result is much smaller than JSON: in the demo below, a two-field message encodes to 8 bytes where the equivalent JSON takes 23. The receiver needs the .proto file to know what field 1 means — which is why the contract matters.

HTTP/2 supplies the plumbing HTTP/1.1 cannot: multiplexing (many calls share one connection, so there is no per-request handshake), header compression (HPACK shrinks repeated headers), and binary framing. A single long-lived connection behaves very differently from many short ones (see our TCP vs UDP guide); gRPC leans on that difference hard. It also uses HTTP/2 features REST rarely touches, like trailers — which is exactly why browsers cannot call it directly, as you will see below.

Illustration of gRPC's two ingredients: a small binary message made of numbered field blocks, riding on a single wide pipe carrying many parallel streams
Protocol Buffers shrink the message; HTTP/2 shrinks the transport. Neither one alone is gRPC — the pair is the point.

The .proto contract: one file, every language

Everything in gRPC starts with a .proto file — a plain-text contract defining your service and its messages. Here is the canonical example from the official gRPC docs:

// The greeter service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Two details deserve attention. First, the field numbers (= 1) are permanent: they are what actually travels on the wire, so you can rename a field later without breaking anything, but you must never reuse a number for a different field. Numbers 1–15 are the cheapest — each tag fits in a single byte — so give the most common fields the lowest numbers. Second, the rpc line declares the method, its request type, and its response type in one place; that is the whole API surface for that method.

Then you run protoc, the protocol buffer compiler, with the gRPC plugin for your language. It generates the client stub, the server skeleton, and the message classes. A Go client and a Python server built from the same .proto agree exactly — no hand-written client, no drift between the docs and the code.

The four kinds of call

A REST endpoint is always one request and one response. gRPC defines four kinds of service method — and the streaming three are where it earns its keep:

  • Unary — one request, one response, just like a normal function call. rpc SayHello(HelloRequest) returns (HelloResponse); This is the default, and the right choice for most calls.
  • Server streaming — one request, a stream of responses. Good for a live feed: stock prices, log tailing, search results arriving as they are found.
  • Client streaming — a stream of requests, one response. Good for uploads, telemetry batches, or a running aggregate.
  • Bidirectional streaming — both sides stream, independently and in any order. The server can answer each message as it arrives ("ping-pong"), or wait for the whole stream first. Good for chat, collaborative editing, or a game loop.

Two guarantees hold across all four: message order is preserved within a single call, and every call ends with a status code. The codes are a fixed set — OK (0) for success, then CANCELLED, UNKNOWN, INVALID_ARGUMENT, DEADLINE_EXCEEDED, NOT_FOUND, PERMISSION_DENIED, UNAVAILABLE (14, the one you retry with backoff), and UNAUTHENTICATED (16). UNAVAILABLE is a retry candidate; INVALID_ARGUMENT is a bug in your request, and retrying it will never help.

Illustration of the four gRPC call types as four lanes: one request and one reply, one request with many replies, many requests with one reply, and two streams flowing both ways
One request, one reply is only the first of four patterns. The streaming three are why teams pick gRPC over plain REST.

A real example: encode a message by hand

The size claim is easy to test: the protobuf wire format is fully specified. I encoded the official docs' own example with a small script — no gRPC library needed, just the rules from the protobuf encoding guide. A message Test1 { int32 a = 1; } with a = 150 encodes to the bytes 08 96 01: tag 08 (field 1, varint wire type), then 96 01, the varint for 150. That matches the protobuf documentation byte for byte.

Then the greeter request: HelloRequest { string name = 1; } with "Ada" encodes to 5 bytes — tag 0a, length 03, and the three letters — against 14 for the equivalent JSON. Add an id field and the gap widens: protobuf 8 bytes, JSON 23. The savings come from two places: field names never travel (only numbers do), and small integers take one byte instead of their decimal digits.

# Hand-encoding a protobuf message (verified against protobuf.dev)
# tag = varint((field_number << 3) | wire_type); wire 0 = varint, 2 = length-delimited
Test1 a=150 -> 08 96 01        (3 bytes, exactly as documented)
HelloRequest name="Ada" -> 0a 03 41 64 61   (5 bytes vs JSON's 14)
id=150 + name="Ada" -> 8 bytes vs JSON's 23 bytes

# What the generated client looks like (Python, after protoc + plugin)
channel = grpc.insecure_channel("localhost:50051")
stub = GreeterStub(channel)
reply = stub.SayHello(HelloRequest(name="Ada"), timeout=5)
print(reply.message)  # "Hello, Ada"

Two honest caveats. First, the demo encodes a message; it does not run a server — this machine has no gRPC library installed. Second, the byte savings matter most at scale: for one call a second, nobody cares; for ten thousand a second between services, smaller payloads and one multiplexed connection are the whole reason gRPC exists. A WebSocket also keeps one connection open, but it gives you a raw pipe — gRPC gives you typed methods, deadlines, and status codes on top.

Where gRPC shines

gRPC is at its best exactly where REST starts to chafe:

  • Service-to-service calls in a polyglot system. When billing is Go, search is Java, and notifications is Python, one .proto file is the shared truth — and generated stubs mean nobody maintains a hand-written client per language.
  • High-frequency, small messages. Telemetry, feature flags, internal APIs called thousands of times a second: binary payloads plus one multiplexed connection beat JSON over HTTP/1.1.
  • Streaming by design. Live updates — a feed, a chat, a progress stream — are built in, not bolted on. A message queue is still the right answer when work must survive a crash; gRPC is for live calls, not durable work.
  • Mobile backends. Small payloads and one connection are kind to battery and bandwidth, which is why several large apps run gRPC between phone and backend.
  • Deadlines and cancellation as first-class features. Every call can carry a deadline (DEADLINE_EXCEEDED if it runs out), and either side can cancel at any time. In REST, timeouts are a client-side afterthought; in gRPC they are part of the call.

Where gRPC does not work

gRPC's strengths are specific, and outside them it fights you. Five limits to know before adopting it:

  1. Browsers cannot call it directly. gRPC puts its status in HTTP trailers, which browser fetch APIs do not expose — so a native browser client is impossible. The workaround is gRPC-Web, a translating proxy. If browsers are your main client, REST is simpler.
  2. Public APIs suffer. A binary format is opaque to curl, to a browser address bar, and to a human reading a log. Public APIs live or die on how easy they are to try — and JSON wins that contest.
  3. Load balancing needs care. gRPC holds one long-lived HTTP/2 connection, so a layer-4 load balancer routing per connection pins all of one client's calls to a single backend. Our load balancer guide covers the layer-4 vs layer-7 split; gRPC needs layer-7 awareness, or client-side balancing.
  4. It is not a queue. A failed gRPC call is gone unless you retry it. If the work must be delivered eventually — a payment, an email, an order — put it on a queue; let gRPC carry the live request, not the guarantee.
  5. A remote call is not a local call. The stub makes it look like one, and that is the trap: networks fail, time out, and deliver twice. Design for partial failure — idempotent handlers, deadlines on every call, retries only for safe codes like UNAVAILABLE — or the abstraction bites under load.
Illustration of gRPC limits: a browser stopped at a gate, a magnifying glass over unreadable binary bytes, and a load balancer sending every call down one stuck connection
The three traps: browsers cannot speak gRPC directly, binary bytes are opaque to humans, and one long-lived connection can defeat a naive load balancer.

gRPC is a typed contract plus a binary format plus HTTP/2: define the service once in a .proto file, generate the client and server in any language, and call remote methods almost like local ones — with four call patterns, deadlines, and a fixed set of status codes built in. It is the right tool when services talk to services, in many languages, many times a second; the wrong tool when the client is a browser, the audience is the public, or the work must survive a crash. For deeper reference, see the official gRPC introduction and the Protocol Buffers encoding guide — both of which this article's examples were verified against.

Frequently asked questions

What is gRPC in simple terms?
gRPC is a framework that lets one program call a function on another program — on a different machine — almost as if it were a local function call. You describe the service once in a .proto file, the tools generate client and server code in your languages, and the calls travel as compact binary messages over HTTP/2 instead of JSON over HTTP/1.1.
What does gRPC stand for?
It is a recursive acronym: "gRPC Remote Procedure Calls". It started inside Google as the open-source successor to its internal Stubby RPC system, and the first stable release, gRPC 1.0, shipped in August 2016. It is now an open-source project under the Cloud Native Computing Foundation.
Is gRPC faster than REST?
Usually, for service-to-service calls: binary Protocol Buffers are smaller than JSON, HTTP/2 multiplexes many calls over one connection, and generated stubs skip the parse-and-map work a REST client does by hand. The gap is biggest for many small calls between services. For a single call from a browser, the difference is rarely what matters.
Does gRPC use JSON?
Not by default. gRPC uses Protocol Buffers — a binary format — as both its interface definition language and its message format. JSON is possible, but it gives up the size and speed advantage, so almost nobody runs gRPC over JSON in production.
Can a browser call a gRPC service directly?
No. Browsers cannot speak gRPC natively, because gRPC relies on HTTP trailers, which browser fetch APIs do not expose. The standard workaround is gRPC-Web: a proxy translates between the browser and the gRPC server. If your API is consumed by browsers, REST is usually the simpler choice.
What is a .proto file?
A .proto file is the contract: a plain-text file that defines your service (its methods) and your messages (their fields and types). The protocol buffer compiler, protoc, plus a gRPC plugin, reads it and generates the client stub and server skeleton in each language you target — so a Java server and a Go client can agree exactly without anyone hand-writing a client.
What are the four types of gRPC call?
Unary (one request, one response, like a normal function call); server streaming (one request, a stream of responses); client streaming (a stream of requests, one response); and bidirectional streaming (both sides stream independently, in any order). Streaming is where gRPC pulls ahead of REST — a single call can carry a live feed of results.
Is gRPC only for microservices?
No, but that is its home turf. It also fits mobile backends (small payloads over one connection), IoT devices, and any polyglot system where services in different languages must agree on an interface. For public APIs, browser clients, and anything humans debug by hand, REST usually wins.

Related articles