Skip to content
API Design Learn/gRPC Fundamentals
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Protocol Buffers & Proto3

5 min read

You'll learn to

  • -Explain what Protocol Buffers are: a typed schema compiled into a compact binary format
  • -See with real bytes that the wire carries field numbers and values, never field names
  • -Explain why a retired field number must never be reused, and how reserved prevents it

REST and GraphQL usually send data as human-readable text, typically JSON, over ordinary HTTP. gRPC takes a different route. Protocol Buffers, or protobuf, define a strongly typed schema that is compiled into a compact binary wire format, and the calls run over HTTP/2, a newer version of HTTP that can carry many calls at once over a single connection. The trade is human readability for smaller messages, faster encoding, and a contract that the compiler enforces rather than one that only convention enforces.

An Analogy: Shorthand Codes

Two people who share a code book can send each other very short messages. Instead of "customer name: Ada Lovelace", they send "2: Ada Lovelace", because both know that field 2 means the customer name. The message is far shorter, but nobody without the code book can read it. Protobuf's field numbers are that code book, and the .proto file is the book.

A Proto3 Message

A basic message definition
syntax = "proto3";

message User {
  int64 id = 1;
  string name = 2;
  string email = 3;
  bool is_verified = 4;
}

A message is protobuf's version of a REST DTO or a GraphQL type: a structured, typed shape. Field types are explicit (int64, string, bool). Unlike JSON, there is no doubt whether a number is an integer or a float, or how big it can be. The type is part of the contract, checked at compile time in every language that protobuf generates code for.

Field Numbers: Not Cosmetic

The = 1, = 2 and = 3 after each field are not ordering hints. They are the identifiers used in the binary format. Protobuf does not send field names at all, which is a large part of why it is so compact compared with JSON, where every key name is repeated in every message. It sends the field number and the value, and the receiver's generated code maps the number back to the field.

The demo builds a real protobuf message by hand, one byte at a time, and compares it with the same data as JSON. It then decodes the bytes to show that only numbers and values were sent. Look at the last two lines: they read old bytes with two different schemas.

Press Run: 19 bytes against 51, no field names on the wire, and what a reused number does
Why field numbers must never be reused after removing a field
message User {
  int64 id = 1;
  string name = 2;
  // string legacy_username = 3;  // REMOVED - but field number 3 must never
                                   // be reused for something else, since old
                                   // binary-encoded messages might still have
                                   // data tagged with field number 3 floating
                                   // around (in logs, queues, caches)
  reserved 3;                     // explicitly reserves it, so a future
                                   // engineer can't accidentally reuse it
  string phone = 4;
}

Since the wire carries only the number, reusing a retired number for a new field of a different type means old serialized data, still tagged with that number in some log or queue, will be read as the new field. The demo's last line shows the result: the text ada99 ends up in a field meant to be a number. reserved makes the retirement explicit and stops the mistake at compile time, instead of relying on every future engineer to remember.

A Service Definition

Declaring an RPC method, the gRPC equivalent of an endpoint
service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc CreateUser (CreateUserInput) returns (User);
}

message GetUserRequest {
  int64 id = 1;
}

A service declares the RPC methods (remote procedure calls) a gRPC server offers, each with an explicit request and response message. It is the direct analog of REST's endpoints or GraphQL's Query and Mutation fields. The compiler generates client and server stub code in each side's language, so on the client a remote call looks like an ordinary local function call.

Because protobuf generates real code from the .proto file, the contract is enforced at compile time in strongly typed languages. A Go client calling a Python server gets a compile error for a type mismatch, not a runtime surprise as a similar mistake in a loosely typed JSON call often would.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Proto Origins in the API Design Lab's gRPC & Event-Driven act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!