Skip to content
learn
  1. Learn
  2. High Level System Design
  3. APIs and Communication

System Design HLD-03.05

gRPC and Protocol Buffers

Service definitions and generated code, compact binary messages, four streaming modes over HTTP/2, deadlines, and why gRPC suits internal traffic.

Intermediate 12 min Last reviewed

The big idea

Inside a large system, services call each other constantly: a single user request can trigger dozens of internal calls. For that traffic, human-readable JSON and hand-written HTTP clients become a cost. JSON is verbose and slow to parse, every team writes its own client code, and nothing checks that the caller and the server agree on field names until something breaks in production.

gRPCA remote procedure call framework from Google that defines services in Protocol Buffers, generates client and server code, and sends binary messages over HTTP/2. treats a remote call like a local function call with a strict contract. You define the service and its messages once in a schema file, a compiler generates typed client and server code in each language, and calls travel as compact binary Protocol BuffersGoogle's language-neutral format for defining structured messages and encoding them as compact binary. over HTTP/2. Mismatches are caught at compile time, payloads shrink, and streaming comes built in.

Think of the difference between two offices exchanging handwritten letters and two offices using pre-printed forms with numbered boxes. The forms are less flexible, but nobody misreads a field, and they are much faster to process.

How it works

Step 1: Define the contract

syntax = "proto3";

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
}

message GetUserRequest { int32 id = 1; }
message User {
  int32 id = 1;
  string name = 2;
  bool active = 3;
  repeated int32 roles = 4;
}

The numbers are field tags, not values. They identify fields on the wire, so names can change freely, but a tag must never be reused for a different meaning. The protoc compiler generates a UserServiceClient with a GetUser method in Go, Java, Python, TypeScript and more, and a server interface to implement.

Step 2: Compact binary encoding

Instead of repeating field names as text, protobuf writes each field as a small tag followed by its value, using variable-length integers where small numbers take one byte:

protobuf.pyruns with python3 (standard library)
import json

# message User { int32 id = 1; string name = 2; bool active = 3; repeated int32 roles = 4; }
user = {"id": 150, "name": "Ada", "active": True, "roles": [1, 2, 3]}

def varint(n):
    out = bytearray()
    while True:
        byte, n = n & 0x7F, n >> 7
        out.append(byte | (0x80 if n else 0))   # high bit = "more bytes follow"
        if not n:
            return bytes(out)

def field(num, wire_type):
    return varint(num << 3 | wire_type)          # tag = field number + wire type

def encode(u):
    name = u["name"].encode()
    packed = b"".join(varint(r) for r in u["roles"])
    return (field(1, 0) + varint(u["id"])
            + field(2, 2) + varint(len(name)) + name
            + field(3, 0) + varint(int(u["active"]))
            + field(4, 2) + varint(len(packed)) + packed)

pb = encode(user)
js = json.dumps(user, separators=(",", ":")).encode()
print("JSON    ", len(js), "bytes:", js.decode())
print("protobuf", len(pb), "bytes:", pb.hex(" "))
print(f"protobuf is {len(pb) / len(js):.0%} of the JSON size")

Output

JSON     53 bytes: {"id":150,"name":"Ada","active":true,"roles":[1,2,3]}
protobuf 15 bytes: 08 96 01 12 03 41 64 61 18 01 22 03 01 02 03
protobuf is 28% of the JSON size

The same user is 53 bytes as compact JSON and 15 bytes as protobuf: 08 means field 1 as an integer, 96 01 is 150 as a varint, 12 03 41 64 61 is field 2, three bytes, "Ada", and so on. Parsing is also cheaper, because there is no text to scan.

Encoded size of one message in JSON and Protocol Buffers Two bars: the user message is 53 bytes as compact JSON and 15 bytes as Protocol Buffers. encoded size of the same User JSON (compact) 53 bytes Protocol Buffers 15 bytes Figure 1. The same message from the code above. Field names are replaced by one-byte tags and numbers by varints. Exact savings depend on the data: text-heavy messages shrink less.

Step 3: Four kinds of call

Because gRPC runs on HTTP/2 streams, a call can carry one message or many in either direction:

The four gRPC call types Four rows, each with a client on the left and a server on the right. Unary: one request, one response. Server streaming: one request, many responses. Client streaming: many requests, one response. Bidirectional streaming: many messages both ways at once. unary: 1 request -> 1 response server streaming: 1 request -> many responses client streaming: many requests -> 1 response bidirectional: many both ways Client Server Client Server Client Server Client Server Figure 2. Unary calls work like REST. Streaming calls keep one HTTP/2 stream open: server streaming for feeds and large result sets, client streaming for uploads and telemetry, bidirectional for chat-like protocols.

Step 4: Deadlines that travel

Every gRPC call can carry a deadlineAn absolute time by which a call must finish. gRPC passes it along to downstream calls, which can give up early once it has passed.. If the edge service gives a request 300 ms and has already spent 120 ms, the downstream call it makes inherits the remaining 180 ms. Services deep in the call chain stop working on requests whose caller has already given up, instead of wasting capacity on answers nobody will read. This is one of gRPC's most valuable features in large systems.

Going deeper

Evolving messages safely

Protobuf is designed for compatibility. Old readers skip fields they do not know, and new readers use defaults for fields that are missing, so you can add fields without coordinating every deployment. The rules: never change a field's tag or type, never reuse a deleted tag (mark it reserved), and treat every field as optional. Break those rules and old and new services silently misread each other's data.

Browsers and public APIs

Browsers cannot speak raw gRPC, because they do not give JavaScript control over HTTP/2 framing and trailers. gRPC-Web and translating proxies exist, but most teams keep REST or GraphQL at the public edge and use gRPC between their own services, often with a gateway translating between the two ( API gateway and backend-for-frontend ).

Trade-offs

OptionWins whenLoses when
gRPC with Protocol Buffers Internal service-to-service calls: typed contracts, small fast messages, streaming, deadlines Browsers and third parties, ad hoc debugging with curl, human-readable payloads
REST with JSON Public APIs, browsers, simple integrations, easy debugging High-volume internal traffic where size, parsing cost and contracts matter
GraphQL Client-facing aggregation across many services Service-to-service calls, where its flexibility adds cost without benefit

Common mistakes

  • Reusing or renumbering field tags, which silently corrupts data between old and new versions.
  • Making calls without deadlines, so a slow dependency ties up threads all the way up the chain.
  • Exposing gRPC directly to browsers and fighting the tooling instead of using a gateway.
  • Assuming binary means secure. Protobuf is an encoding, not encryption; use TLS.

Check yourself

  1. What do the numbers in a protobuf message definition, like name = 2, mean?

    Show answer

    B. Field tags used to identify fields on the wire Tags, not values. They must stay stable, because the binary encoding uses them instead of names.

  2. Why are protobuf messages usually smaller than JSON?

    Show answer

    B. Field names are replaced by small numeric tags and numbers use compact varints Binary tags and varints avoid repeating field names and digits as text.

  3. A client wants a live stream of price updates after one subscription request. Which call type fits?

    Show answer

    B. Server streaming One request, then many responses from the server over the same stream.

  4. What problem do propagated deadlines solve?

    Show answer

    B. Downstream services wasting work on requests the caller has already abandoned Each hop knows how much time is left and stops early once the deadline has passed.

Recap

  • gRPC defines services and messages in Protocol Buffers and generates typed clients and servers.
  • Binary encoding with field tags and varints makes messages small and fast to parse.
  • On HTTP/2, calls can be unary, server streaming, client streaming or bidirectional.
  • Deadlines propagate down the call chain so abandoned work stops early.
  • Use gRPC inside your system and REST or GraphQL at the public edge.

Get new lessons by email

Get new posts on backend and AI internals. No spam, unsubscribe anytime.

Your email is only used to send new posts. Privacy

Next up