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.
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.
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.
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_EXCEEDEDif 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:
- 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.
- 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.
- 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.
- 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.
- 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.
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
What Is a DNS Record? 9 Record Types Explained (With a Real dig Demo)
What is a DNS record? 9 types — A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, CAA — explained with dig output from a live domain and the mistakes that break sites.
Web DevelopmentWhat Are Server-Sent Events? 7 Things Every Developer Should Know (With Examples)
What are server-sent events? Learn how SSE streams live updates over plain HTTP — event format, EventSource, reconnection, SSE vs WebSocket and a verified demo.
Web DevelopmentWhat Is a URL Slug? 7 Things Every Developer Should Know (With Examples)
What is a URL slug? Learn how slugs work — anatomy, Google's hyphen rule, a verified slugify demo, non-ASCII handling, and when never to rename one. Read on.