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.