Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Communication

RPC, gRPC and Protocol Buffers

Learn how RPC and gRPC work between microservices: contract-first design, Protocol Buffers binary encoding, streaming and safe field versioning, with runnable stand-ins.

REST thinks in resources: you GET a product or POST an order. RPC (remote procedure call) thinks in actions: you call reserveStock(sku, quantity) and the framework hides the network. Inside a company, where the same teams control both sides, RPC is a popular choice because calls are compact, typed and fast.

The best-known modern RPC system is gRPC. It runs over HTTP/2, describes every call in a Protocol Buffers (protobuf) file, and generates client and server code in many languages. This lesson explains what that buys you, how protobuf stores data, and how to change a contract without breaking callers. The real gRPC stack cannot run on this site, so its definitions are read-only, and the examples that run are stand-ins that show the same ideas.

What gRPC gives you

Contract first One .proto file describes every call.
Generated code Typed clients and servers in many languages.
Binary format Small messages, fast to parse.
Streaming Many messages on one call.
1 / 2

Contract first

With gRPC you write the contract before the code, in a .proto file. It lists the messages (data shapes) and the services (calls). Everything else, including client libraries and server skeletons, is generated from it.

This is real protobuf syntax, shown read-only because the compiler and gRPC runtime are not available in the browser:

PROTO
syntax = "proto3";

package inventory.v1;

service Inventory {
  // One request, one response.
  rpc GetStock(GetStockRequest) returns (StockLevel);

  // One request, many responses over time.
  rpc WatchStock(GetStockRequest) returns (stream StockLevel);
}

message GetStockRequest {
  string sku = 1;
}

message StockLevel {
  string sku = 1;
  int32 available = 2;
  string warehouse = 3;
}

A generated Java client then offers a method like inventoryStub.getStock(request), and a Go server implements an interface with the same method. Because both sides compile against the same file, a type mismatch is a build error and not a production surprise. Compare this with REST, where the contract is documentation that nothing forces anyone to follow (Synchronous Communication with HTTP APIs).

The four call styles

gRPC uses HTTP/2, which can carry many streams of messages on one connection, so a call is not limited to one request and one reply.

  • Unary. One request, one response. The ordinary case.
  • Server streaming. One request, a stream of responses: a price feed, progress updates, a large result in chunks.
  • Client streaming. A stream of requests, one response: uploading a file in pieces, then getting a summary.
  • Bidirectional streaming. Both sides send streams independently: chat, live collaboration.

Streaming also needs deadlines. A gRPC client passes a deadline with each call, and the framework propagates it to downstream calls, so a request that is already too late can be abandoned everywhere. It is the same idea as the timeouts in the previous lesson, built into the protocol.

How protocol buffers store data

JSON repeats field names in every message: {"sku":"sku-1","available":5}. Protobuf does not send names at all. Each field is written as a tag (the field number plus a wire type) followed by its value:

  • Integers use a varint: small numbers take one byte, and each byte carries 7 bits of the number plus a flag saying "more bytes follow".
  • Strings and nested messages use length-delimited encoding: a length, then the bytes.

The stand-in below implements just those two kinds so you can see the bytes. It is a teaching sketch of the real wire format, not a replacement for a protobuf library: there is no support for negative numbers, floats, nested messages or repeated fields.

Node.js Encoding a message the protobuf way

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The number 150 needs two bytes (9601) because it does not fit in 7 bits, while a count like 5 would take a single byte. The field names sku and available do not appear anywhere in the binary output; the receiver recovers them from the field numbers using the same schema. That is why the contract file matters so much: without it, the bytes are meaningless.

Changing a contract safely

Those field numbers are the most important part of a .proto file, because they are the wire format. The rules follow directly:

  • Never change or reuse a field number for a different meaning. An old client would read the new data as the old field.
  • Adding a field with a new number is safe. Old readers skip numbers they do not know, and new readers see a default value when an old writer leaves it out.
  • Removing a field: stop using it, and mark its number (and name) reserved so nobody reuses it later.
  • Renaming a field is safe on the wire (names are not sent) but breaks generated code and JSON mappings, so do it with care.
  • Do not change a field's type unless the wire types are compatible.
PROTO
message StockLevel {
  reserved 4;
  reserved "legacy_count";

  string sku = 1;
  int32 available = 2;
  string warehouse = 3;
  int64 updated_at_unix = 5;   // new field: old clients ignore it
}

Putting a version in the package name (inventory.v1) gives you an escape hatch for the rare change that cannot be made compatibly. The wider discipline is covered in API Versioning and Evolving Contracts.

An RPC stand-in with JSON-RPC

You do not need gRPC to try the RPC style. JSON-RPC is a small, much older standard: the caller posts {"method": "...", "params": ..., "id": 1} and receives either a result or an error. There is a single endpoint, and the method name picks the action. The stand-in below runs a real HTTP server on the loopback interface and a tiny client that makes calls look like local function calls.

Node.js A JSON-RPC server and a typed-looking client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The wrapper hides HTTP, but it cannot hide that the call can fail in new ways (network, timeout, server error). That is the oldest warning about RPC: a remote call that looks local invites you to forget the fallacies of distributed computing. gRPC generates the wrapper for you, and you still have to handle errors and deadlines.

REST, gRPC or messaging?

There is no winner, only trade-offs.

  • Choose REST/JSON for public APIs, browser clients and anything where readability and ubiquity matter most.
  • Choose gRPC for internal, high-volume, latency-sensitive calls between services you control, especially across several languages, or when you need streaming.
  • Choose messaging (Asynchronous Messaging and Events) when the sender does not need an immediate answer.

Many systems use all three: REST at the edge (API Gateway and Backend for Frontend), gRPC between core services and events for everything that can wait.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does 'contract first' mean in gRPC?

    The .proto file is the single source of truth, so both sides compile against the same definition.
  2. 2. Why are protobuf messages usually smaller than the same JSON?

    Names are known from the schema, so only tags and values go over the wire, with integers stored as varints.
  3. 3. Which change to a .proto message is NOT safe?

    Old clients would interpret the new data as the old field. Field numbers must never change meaning.
  4. 4. Which gRPC call style has the server send many responses to one request?

    Server streaming sends a stream of responses, useful for feeds and progress updates.
  5. 5. What is the main danger of making remote calls look like local function calls?

    Hiding the network does not remove latency or partial failure. Handle errors and set deadlines.

Summary

  • RPC models calls as actions; gRPC runs over HTTP/2 with contracts written in .proto files and generated code.
  • Protobuf sends field numbers and compact binary values, so messages are small and names are not on the wire.
  • Never change or reuse a field number; add new fields with new numbers and reserved the old ones.
  • gRPC supports unary, server, client and bidirectional streaming and carries deadlines.
  • Remote calls can still fail; use REST at the edge, gRPC for internal calls and messaging when no immediate answer is needed.

Next: API Gateway and Backend for Frontend.