What is gRPC?
gRPC lets one program call a function in another program over the network as if it were local. You describe the functions and their data in a .proto file, a tool generates code for both sides, and each call travels as an HTTP/2 stream carrying small binary Protocol Buffers messages.
It is popular for services talking to each other inside companies and for mobile apps that need speed. Calls can be one request and one reply, or streams in either direction. Deadlines, cancellation and clear status codes are built in, which keeps large systems from piling up stuck requests.
Think of it like this. A REST API is like posting a letter in your own words and hoping the reader understands. gRPC is like filling in a printed form that both offices agreed on: every box has a number and a type, so it is quick to fill, quick to read, and nobody argues over what a field means. The deadline is the line on the form that says reply by noon or forget it.
Step by step
Normal
4 stepsThe checkout service asks the inventory service: how many of this tea are in stock?
Normal
4 stepsThe checkout service asks the inventory service: how many of this tea are in stock?
- 1
Call starts
HEADERS name the function
Calling GetStock in code becomes an HTTP/2 POST. The path names the service and method. The connection was opened earlier and is reused for every call.
- 2
Request message
A tiny protobuf in a DATA frame
The request is encoded with Protocol Buffers: compact binary, not text. A 5-byte prefix says how long it is.
- 3
Reply
Headers and a protobuf answer
The server answers on the same stream with :status 200 and a DATA frame holding the reply message.
- 4
Trailers
grpc-status: 0 means OK
The real result comes last, in trailers. HTTP 200 only means the HTTP part worked; grpc-status says whether the call itself succeeded.
Streaming
4 stepsA stock dashboard subscribes to live updates. One call, many replies, until it stops watching.
Streaming
4 stepsA stock dashboard subscribes to live updates. One call, many replies, until it stops watching.
- 1
Subscribe
One request opens the stream
WatchStock is a server streaming method. The caller sends one request and keeps the stream open.
- 2
Updates flow
Each change is a new message
Every time stock changes, the server sends another length-prefixed message on the same stream. No polling, no new requests.
- 3
Flow control
WINDOW_UPDATE keeps it moving
HTTP/2 flow control stops a fast sender from flooding a slow reader. The reader opens the window as it consumes messages.
- 4
Stop watching
RST_STREAM with CANCEL
When the dashboard closes, the client cancels the call. The server sees the cancel and stops the work. The client side reports status CANCELLED.
Deadline exceeded
4 stepsThe database is slow. The checkout will only wait 300 ms, so the call is cancelled instead of hanging.
Deadline exceeded
4 stepsThe database is slow. The checkout will only wait 300 ms, so the call is cancelled instead of hanging.
- 1
Call with a deadline
grpc-timeout: 300m
The checkout must answer the shopper quickly, so it gives the call 300 milliseconds. The deadline travels with the request.
- 2
Slow database
The inventory service is stuck waiting
The inventory service asks the database, which is busy. Good servers pass the remaining time on, so the database query has a deadline too.
- 3
Time is up
Cancel, then DEADLINE_EXCEEDED
At 300 ms the checkout's library cancels the stream with RST_STREAM and reports status 4, DEADLINE_EXCEEDED, to the code. No thread is left waiting forever.
- 4
Work stops everywhere
The cancel spreads
The load balancer passes the cancel on. The inventory service sees its call was cancelled and stops the database query. The checkout shows a fallback, such as usually ships in 2 days.
Myths and mix-ups
- An HTTP 200 means the gRPC call worked; the real result is grpc-status in the trailers.
- gRPC only works with Protocol Buffers; protobuf is the default, but other formats can be plugged in.
- Browsers can call gRPC services directly; they cannot read HTTP/2 trailers from page code, so they need gRPC-Web and a proxy.
- A call without a deadline is safe; it can hang forever and tie up threads when something downstream is slow.
Try it yourself
Run these on your own computer to see gRPC at work.
List services on a server
grpcurl -plaintext localhost:50051 listNeeds grpcurl and a server with reflection turned on. Drop -plaintext for TLS servers.
Call a method
grpcurl -plaintext -d '{"sku":"TEA-0042"}' localhost:50051 inventory.v1.Inventory/GetStockSends JSON, grpcurl turns it into protobuf and prints the reply as JSON.
Set a deadline
grpcurl -plaintext -max-time 0.3 -d '{"sku":"TEA-0042"}' localhost:50051 inventory.v1.Inventory/GetStockGives up after 0.3 seconds, like the deadline scenario.
Check a health endpoint
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/CheckMany servers offer the standard health check service.
gRPC at a glance
- Layer
- Application (7)
- Runs on
- HTTP/2 (stream per call)
- Port
- Any; often 443, or 50051 in examples
- Data format
- Protocol Buffers (binary)
- Call types
- Unary, server stream, client stream, two-way stream
- Result
- grpc-status in trailers (0 is OK)
- First released
- 2015 (1.0 in 2016)
Defined ingRPC over HTTP/2 protocol specRFC 9113Protocol Buffers
Header fields
What gRPC puts in its messages, with example values from the stories above.
gRPC message
- Compressed flag
00 means the message is not compressed.- Message length
15Five bytes of prefix tell the reader exactly where each message ends.- Protobuf type
inventory.v1.GetStockRequestBoth sides compiled the same .proto file, so they agree on what every byte means.
HTTP/2 HEADERS (0x1)
- Type
HEADERS (0x1)- Flags
0x05 (END_STREAM, END_HEADERS)- Stream ID
1Each gRPC call is one HTTP/2 stream. Many calls share one connection.- grpc-status
0 (OK)Other common codes: 3 invalid argument, 4 deadline exceeded, 5 not found, 14 unavailable, 16 unauthenticated.- grpc-message
(none)- :path
/inventory.v1.Inventory/...The function to call: /package.Service/Method.- content-type
application/grpcTells proxies and the server this is gRPC, not a normal web request.- grpc-timeout
300mThe deadline: how long the caller is willing to wait. m means milliseconds, S seconds.
Test yourself
What does gRPC run on?
Questions people ask
What is the difference between gRPC and REST?
REST usually sends JSON over HTTP with URLs and verbs you design yourself. gRPC uses a shared .proto contract, binary messages and HTTP/2 streams, with generated code and built-in streaming and deadlines.
What port does gRPC use?
Any port you choose. Public services often use 443. Many examples and local setups use 50051.
Can a browser call gRPC?
Not directly, because page code cannot control HTTP/2 framing or read trailers. gRPC-Web, with a proxy in front of the server, fills the gap.
Is gRPC faster than REST?
Usually its messages are smaller and quicker to encode, and one connection carries many calls. For simple public APIs the difference is often small.
What does DEADLINE_EXCEEDED mean in gRPC?
The caller's time limit ran out before a reply came. Check what is slow downstream, and make sure each service passes the remaining time on to its own calls.