gRPC Explained: Protobuf, Streaming and When to Use It
gRPC is a binary RPC framework over HTTP/2. Learn the protobuf schema, the four call types, and when REST is the better choice.
By Velloreth
The schema
syntax = "proto3";
service UserService {
rpc GetUser (GetUserRequest) returns (User);
rpc ListUsers (ListUsersRequest) returns (stream User);
}
message GetUserRequest {
string id = 1;
}
message User {
string id = 1;
string name = 2;
string email = 3;
}
The schema defines the service and the messages.
A code generator produces the client and the server stubs.
The encoding
Protobuf is a binary encoding.
| JSON | Protobuf | |
|---|---|---|
| Format | text | binary |
| Size | larger | smaller |
| Parse | slower | faster |
| Schema | optional | required |
| Readable | yes | no |
The field number is the wire format, so it must not change.
A field name can change without breaking the wire format.
The transport
gRPC runs over HTTP/2.
The benefits:
- Multiplexing, so several calls share one connection
- Header compression
- Streaming in both directions
- A binary frame
The consequence: a browser cannot speak raw gRPC, because it cannot control the frames.
The four call types
| Type | Request | Response |
|---|---|---|
| Unary | one | one |
| Server streaming | one | a stream |
| Client streaming | a stream | one |
| Bidirectional | a stream | a stream |
Unary is the common case, and it is like a REST call.
Server streaming is used for a large result or a live feed.
Bidirectional is used for a chat or a real-time collaboration.
The code
// Server
server.addService(UserService.service, {
getUser: (call, callback) => {
callback(null, { id: call.request.id, name: 'Alice' });
},
});
// Client
const user = await client.getUser({ id: '1' });
The generated stub hides the transport.
A call looks like a local function, which is the point of an RPC.
The errors
A status code and a message.
| Code | Meaning |
|---|---|
| OK | success |
| INVALID_ARGUMENT | a bad request |
| NOT_FOUND | missing |
| PERMISSION_DENIED | not allowed |
| UNAUTHENTICATED | no credential |
| DEADLINE_EXCEEDED | a timeout |
| UNAVAILABLE | a transient failure |
| INTERNAL | a server error |
A deadline is set per call, and it propagates to the downstream calls.
A retry is configured per method, and it must be safe for a non-idempotent call.
The browser
A browser cannot call gRPC directly.
The options:
| Option | How |
|---|---|
| gRPC-Web | a proxy translates |
| Connect | a protocol that works over HTTP/1.1 |
| A REST gateway | a transcoding proxy |
A public API is almost always REST or GraphQL, and gRPC is for the internal calls.
When to use it
Use gRPC for:
- A service-to-service call
- A high-throughput internal API
- A streaming case
- A polyglot system where the schema is the contract
Use REST for:
- A public API
- A browser client
- A resource that benefits from HTTP caching
- A simple CRUD
The breaking changes
Safe:
- Add a new field with a new number
- Add a new method
- Mark a field as reserved
Breaking:
- Change a field number
- Change a field type incompatibly
- Remove a field a client still sends
- Rename a service or a method
The field numbers are the contract, and a reserved range prevents a reuse.
Common mistakes
A changed field number. A wire incompatibility.
No deadline. A hung call.
A retry on a non-idempotent call. A duplicate.
A browser client without a proxy. It does not work.
A public API in gRPC. A client cannot call it.
No schema versioning. A breaking change.
A large message. The default size limit is exceeded.
No load balancing. A single connection to one backend.
A debug log of a binary payload. Unreadable.
No health check. A broken service is not removed.
A quotable summary
gRPC is an RPC framework that uses a protobuf schema and a binary encoding over HTTP/2, with four call types: unary, server streaming, client streaming and bidirectional streaming. The schema generates the client and the server stubs, the field numbers are the wire contract, and a browser needs a proxy because it cannot speak raw gRPC. Use it for a service-to-service call, and REST or GraphQL for a public API.
Related reading
For the related topics, see rest-api-design-principles and graphql-basics. For the broader context, http-status-codes-explained and api-authentication-methods.