gRPC is a framework for building fast network APIs, and Protocol Buffers are the structured message format commonly used with it. This cheat sheet helps students understand how clients, servers, messages, and services fit together in a modern distributed system. It is useful for reading .proto files, designing APIs, and debugging communication between programs.
Students need these ideas when building scalable applications that exchange typed data across a network.
The core idea is that a .proto file defines messages and services, then code generation creates client and server stubs. gRPC usually runs over HTTP/2, which supports multiplexing, headers, binary framing, and streaming. Protocol Buffers encode data using field numbers, types, and wire formats, so schema design affects compatibility. Safe API evolution depends on rules such as never reusing field numbers and adding new fields in a backward-compatible way.
Key Facts
- A .proto file defines message types with fields using the pattern type name = field_number, such as string user_id = 1.
- A gRPC service defines callable methods using rpc MethodName(RequestType) returns (ResponseType).
- Unary RPC means one request produces one response, while server streaming, client streaming, and bidirectional streaming use stream before the message type.
- Protocol Buffers use field numbers, not field names, in the binary encoding, so field numbers must stay stable after release.
- A safe schema change is adding a new optional field with a new field number, because older clients can ignore unknown fields.
- Do not reuse or change the meaning of an old field number, because stored data or older clients may decode the value incorrectly.
- gRPC status codes report call results, such as OK for success, INVALID_ARGUMENT for bad input, NOT_FOUND for missing resources, and UNAVAILABLE for temporary service failure.
- HTTP/2 helps gRPC performance by allowing multiple simultaneous streams over one connection and by sending compact binary frames.
Vocabulary
- gRPC
- A remote procedure call framework that lets a program call methods on another program over a network using generated client and server code.
- Protocol Buffers
- A compact binary serialization format that stores structured data according to message definitions in a .proto schema.
- Service Definition
- The part of a .proto file that lists the RPC methods a server provides and the request and response message types for each method.
- Stub
- Generated code that lets a client call a remote gRPC method as if it were a local function.
- Streaming RPC
- A gRPC method that sends a sequence of messages from the client, the server, or both instead of only one request and one response.
- Backward Compatibility
- The ability of newer schemas or services to work correctly with older clients, older servers, or previously stored data.
Common Mistakes to Avoid
- Reusing a deleted field number is wrong because old binary data may still contain that number and could be decoded as the new meaning.
- Changing a field type after release is wrong because existing clients may decode the same bytes using the old type and produce incorrect values.
- Treating gRPC as the same as REST is wrong because gRPC centers on service methods, generated stubs, binary messages, and HTTP/2 rather than resource URLs and JSON by default.
- Forgetting to handle gRPC status codes is wrong because network calls can fail, time out, or return application errors even when the program compiles.
- Putting too much business logic in generated code is wrong because generated stubs and message classes may be overwritten when the .proto file is regenerated.
Practice Questions
- 1 A message has fields string name = 1, int32 age = 2, and bool active = 3. Which field number should be used for a new optional email field, and why?
- 2 Write a unary gRPC service method signature for GetUser that takes GetUserRequest and returns GetUserResponse.
- 3 A server sends 20 updates to one client after receiving a single request. Which RPC pattern is this: unary, server streaming, client streaming, or bidirectional streaming?
- 4 Explain why changing field names is usually less dangerous than changing field numbers in a Protocol Buffers schema.
Understanding gRPC & Protocol Buffers Reference
A gRPC API is a contract between separate programs. The contract does more than list data fields. It decides which inputs are valid, which results are promised, and which failures a caller must handle.
Generated client code can make a remote call look like an ordinary function call. That convenience can hide an important fact.
The call crosses a network, so it can be slow, interrupted, duplicated, or rejected. Good API users treat every response as uncertain until the server confirms success.
Protocol Buffers save space because each message is encoded as compact binary data. A receiver reads tags that identify fields, then interprets the following bytes according to the expected type. This explains why a type change can be dangerous even when a field name looks unchanged in the schema.
A string, a whole number, and nested message data have different encodings. Students should learn the difference between a field being absent and a field holding its default value. In newer protobuf designs, explicit presence can show whether a sender supplied a value.
This matters for updates. A missing value might mean leave the old value alone, while an empty value might mean clear it.
HTTP/2 carries each RPC in its own stream within a shared connection. Streams prevent a slow upload from blocking every other call in the same connection. They still have limits.
Both sides use flow control to avoid accepting data faster than they can process it. In streaming code, a server should read messages steadily and a client should not send an unlimited queue at once.
Each stream preserves the order of its own messages, but separate RPCs can finish in a different order. This is important in chat, live sensor feeds, file transfer, and multiplayer programs.
A real call needs a deadline. A deadline tells the server and client when to stop waiting. Without one, stuck calls can hold memory, connections, or worker threads for far too long.
Cancellation is related. If a user closes a page or a program no longer needs a result, it should cancel the request. Servers should notice cancellation and stop expensive work when possible.
Metadata carries small extra details with a call, such as an authorization token, language preference, or request identifier. Sensitive data needs encrypted transport and careful logging. A token printed in a debug log can become a security problem.
Error handling should match the meaning of the failure. Bad input should be fixed by the caller, while a temporary unavailable service may justify a retry after a delay. Retrying every failure is unsafe.
A network break can happen after the server has completed an action but before the client receives the reply. Repeating a payment or order creation could create duplicates. APIs often use idempotency keys or request identifiers to make repeated requests safe.
When changing a schema, teams reserve removed field numbers and test old clients against new servers. Compatibility is not just a file rule. It is a promise that software released at different times can still communicate.