gRPC & Protobuf Contract Design

gRPC & Protobuf Contract Design

REST contracts are JSON over HTTP with conventions you enforce by discipline. gRPC contracts are compiled — the .proto file is the single source of truth, and the compiler generates strongly-typed client and server code in every supported language from it. This shifts a whole category of bugs (typos in field names, wrong types, missing required fields) from runtime to compile time, at the cost of needing a compilation step and losing casual browser/curl debuggability. This guide covers designing .proto contracts, choosing the right RPC shape, and keeping the contract backward-compatible as it evolves.

1. A Full Annotated .proto File

syntax = "proto3";
 
package orders.v1;
 
// --- Messages ---
 
message Order {
  int64 id = 1;
  int64 customer_id = 2;
  OrderStatus status = 3;
  repeated LineItem items = 4;
  double total_amount = 5;
 
  // oneof: exactly one of these is set — models a discriminated union
  oneof discount {
    double percentage_discount = 6;
    double fixed_discount = 7;
  }
}
 
message LineItem {
  int64 product_id = 1;
  int32 quantity = 2;
  double unit_price = 3;
}
 
enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;  // proto3 enums MUST have a zero value — this is it
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_SHIPPED = 2;
  ORDER_STATUS_CANCELLED = 3;
}
 
message GetOrderRequest  { int64 order_id = 1; }
message GetOrderResponse { Order order = 1; }
 
message CreateOrderRequest  { int64 customer_id = 1; repeated LineItem items = 2; }
message CreateOrderResponse { Order order = 1; }
 
message ListOrdersRequest  { int64 customer_id = 1; int32 page_size = 2; string page_token = 3; }
message OrderEvent         { Order order = 1; string change_type = 2; }  // for server streaming
message OrderUpdate        { int64 order_id = 1; OrderStatus new_status = 2; }  // for client streaming
message BatchUpdateSummary { int32 updates_applied = 1; }
 
// --- Service ---
 
service OrderService {
  // Unary: one request, one response — the gRPC equivalent of a REST GET/POST
  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
 
  // Server streaming: one request, a stream of responses
  rpc WatchOrderEvents(ListOrdersRequest) returns (stream OrderEvent);
 
  // Client streaming: a stream of requests, one response
  rpc BatchUpdateStatus(stream OrderUpdate) returns (BatchUpdateSummary);
 
  // Bidirectional streaming: both sides stream independently
  rpc SyncOrders(stream OrderUpdate) returns (stream OrderEvent);
}

2. The Four RPC Types

Unary RPC

One request in, one response out — functionally equivalent to a REST call.

Server streaming RPC

Client sends one request; server pushes a stream of responses over the same connection until it closes the stream. Good for subscriptions, live feeds, or a large result set delivered incrementally.

Client streaming RPC

Client pushes a stream of messages; server reads them all and returns a single summary response once the client's stream ends. Good for batch uploads or aggregating many small updates into one commit.

Bidirectional streaming RPC

Both sides stream independently over the same long-lived connection — reads and writes interleave freely, in either order, on either side. Good for real-time sync, chat, or collaborative editing.

3. Protobuf Field Numbering and Backward Compatibility

The field number, not the name, is the wire identity of a field. This table is the single most interview-relevant fact about protobuf.

message Order {
  int64 id = 1;
  int64 customer_id = 2;
  reserved 3;            // was `legacy_discount_code` — removed, number retired forever
  reserved "legacy_discount_code";
  OrderStatus status = 4;
}

Versioning gRPC services

4. gRPC vs REST

5. Error Handling in gRPC

gRPC uses a fixed set of status codes (io.grpc.Status), roughly analogous to but distinct from HTTP status codes — they travel in trailing metadata rather than as an HTTP status line.

// Rich error details attach structured data beyond the status code + message,
// via google.rpc.Status and the standard error_details.proto types.
import "google/rpc/error_details.proto";

// Server side: returning a rich, typed error
throw Status.FAILED_PRECONDITION
    .withDescription("Cannot cancel an order that has already shipped")
    .asRuntimeException();

Deadlines and cancellation

Every gRPC call should carry a client-set deadline — not a fire-and-forget timeout guessed by the server, but an explicit budget the client propagates down the call chain.

// Client sets a 500ms deadline; if exceeded, the call fails with DEADLINE_EXCEEDED
// and the server-side work is signaled to cancel via the call's Context.
orderServiceStub
    .withDeadlineAfter(500, TimeUnit.MILLISECONDS)
    .getOrder(request);

6. gRPC-Gateway: Bridging to HTTP/JSON

gRPC-Gateway generates a reverse-proxy that translates RESTful HTTP/JSON requests into gRPC calls against the same service — one .proto file drives both the internal gRPC contract and the external REST facade.

import "google/api/annotations.proto";
 
service OrderService {
  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse) {
    option (google.api.http) = {
      get: "/v1/orders/{order_id}"
    };
  }
}

A browser client can now call GET /v1/orders/1041 as plain JSON over HTTP, while internal services call the same GetOrder RPC natively over gRPC — both paths are generated from, and stay consistent with, one .proto source of truth.

7. Message Design: Nesting, Maps, and Well-Known Types

Nested messages vs separate top-level messages

Protobuf lets you nest a message definition inside another, scoping it to the parent — useful when a type genuinely has no meaning outside its container.

message Order {
  int64 id = 1;
 
  // Nested: Address only ever exists in the context of an Order
  message Address {
    string street = 1;
    string city = 2;
    string postal_code = 3;
  }
 
  Address shipping_address = 2;
  Address billing_address = 3;
}

If Address is reused across multiple unrelated messages (Customer, Warehouse, Order), promote it to a top-level message instead — nesting it under Order would force every other file to import and reference Order.Address, coupling unrelated services to Order's definition.

Maps

message Order {
  int64 id = 1;
  map<string, string> metadata = 2;  // arbitrary key-value tags, e.g. {"source": "mobile-app"}
}

Maps are convenient for loosely-structured metadata, but every key/value pair is untyped and unvalidated by the schema — prefer explicit fields for anything the server logic actually branches on. A map<string, string> is for data the service passes through, not data it interprets.

Well-known types

Protobuf ships a standard library of reusable message types so teams don't reinvent Timestamp or Duration incompatibly across services.

import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";
 
message Order {
  int64 id = 1;
  google.protobuf.Timestamp created_at = 2;
}
 
message UpdateOrderRequest {
  Order order = 1;
  google.protobuf.FieldMask update_mask = 2;  // e.g. "status,total_amount" — PATCH semantics for gRPC
}

8. Interceptors and Cross-Cutting Concerns

Interceptors are gRPC's equivalent of REST middleware — code that wraps every call (client-side or server-side) without the service implementation needing to know about it. They're the standard place for concerns that would otherwise be copy-pasted into every RPC handler.

// Server interceptor: reject calls with no/invalid auth token before the handler ever runs
public class AuthInterceptor implements ServerInterceptor {
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
            ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
        String token = headers.get(AUTH_TOKEN_KEY);
        if (!isValid(token)) {
            call.close(Status.UNAUTHENTICATED.withDescription("invalid token"), new Metadata());
            return new ServerCall.Listener<>() {};
        }
        return next.startCall(call, headers);
    }
}

Interview Questions

• Why does renaming a protobuf field never break compatibility, but changing its field number always does?
• Walk through all four gRPC RPC types (unary, server-streaming, client-streaming, bidirectional) and give a realistic use case for each.
• What does reserved do in a .proto file, and what bug does it prevent?
• Why must every proto3 enum have a zero value, and what happens when an old client receives a newer enum value it doesn't recognize?
• Compare gRPC and REST across wire format, browser support, and streaming support. When would you choose each?
• How do gRPC deadlines differ from a simple client-side timeout, and why does deadline propagation matter across a multi-hop call chain?
• What problem does gRPC-Gateway solve, and why is it preferable to maintaining a separate hand-written REST API alongside the gRPC one?
• Map three gRPC status codes to their closest HTTP status code equivalents, and explain one case where the mapping isn't clean.
• When would you nest a message type inside another versus promoting it to a top-level message?
• What does google.protobuf.FieldMask solve, and why can't a unary RPC distinguish "field explicitly set to zero" from "field left unset" without it?
• What are gRPC interceptors, and which cross-cutting concerns are best implemented as one instead of duplicating logic in every handler?