Skip to content
Velloreth
Technology 4 min read

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

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.

JSONProtobuf
Formattextbinary
Sizelargersmaller
Parseslowerfaster
Schemaoptionalrequired
Readableyesno

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

TypeRequestResponse
Unaryoneone
Server streamingonea stream
Client streaminga streamone
Bidirectionala streama 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.

CodeMeaning
OKsuccess
INVALID_ARGUMENTa bad request
NOT_FOUNDmissing
PERMISSION_DENIEDnot allowed
UNAUTHENTICATEDno credential
DEADLINE_EXCEEDEDa timeout
UNAVAILABLEa transient failure
INTERNALa 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:

OptionHow
gRPC-Weba proxy translates
Connecta protocol that works over HTTP/1.1
A REST gatewaya 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.

For the related topics, see rest-api-design-principles and graphql-basics. For the broader context, http-status-codes-explained and api-authentication-methods.

Frequently asked questions

What is gRPC?
It is a remote procedure call framework that uses a protobuf schema and a binary encoding over HTTP/2. The schema defines the service and the messages, and a code generator produces the client and the server stubs. It is used for a service-to-service call, where the performance and the schema matter.
What is protobuf?
Protocol Buffers, a language-neutral schema and a binary encoding. A message is defined in a .proto file with numbered fields, and the encoding is compact and fast to parse. The field numbers are the wire format, so they must not change.
What are the four call types?
Unary, which is one request and one response; server streaming, which is one request and a stream of responses; client streaming, which is a stream of requests and one response; and bidirectional streaming, which is a stream in both directions.
Why can a browser not call gRPC directly?
Because a browser cannot control the HTTP/2 frames that gRPC needs. The workaround is gRPC-Web, which uses a proxy to translate, or a Connect-style protocol that works over HTTP/1.1. A browser client is therefore a special case.
When should I use gRPC instead of REST?
For a service-to-service call where the performance, the schema and the streaming matter. REST is better for a public API, for a browser client, and for a resource that benefits from HTTP caching. A public API is almost always REST or GraphQL.
What is a breaking change in protobuf?
Changing a field number, changing a field type incompatibly, or removing a field that a client still sends. The safe changes are to add a new field with a new number and to mark an old one as reserved. The field numbers are the contract.