Designing Service Contracts
You'll learn to
- -Split a gRPC system into focused services, each owning one domain
- -Give even an empty request its own message type, and see why that helps later
- -Use well-known types such as Timestamp, and see what goes wrong with home-made time formats
A real gRPC system is rarely one giant service. It is usually several focused services, each owning a clear domain and calling the others when needed. Drawing those boundaries well is the gRPC counterpart of the resource-modeling discipline from the REST modules, applied to service responsibilities instead of URL paths.
An Analogy: A Hospital's Departments
A hospital has a pharmacy, a radiology department and an admissions desk. Each has its own staff, its own rules and its own opening hours, and each can change how it works without asking the others. A patient forms do not mix pharmacy fields into the admissions form. Services work the same way: one domain, one owner, one contract.
Multi-Service Design
service OrderService {
rpc CreateOrder (CreateOrderRequest) returns (Order);
rpc GetOrder (GetOrderRequest) returns (Order);
}
service InventoryService {
rpc CheckStock (CheckStockRequest) returns (StockLevel);
rpc ReserveStock (ReserveStockRequest) returns (ReservationResult);
}Splitting OrderService and InventoryService, instead of one combined CommerceService, mirrors the single-responsibility instinct from LLD. Each service can be owned, versioned, scaled and deployed independently by the team for that domain. A client that only needs order operations never has to know inventory message types exist.
Empty Messages: Explicit, Not Absent
service HealthService {
rpc Check (HealthCheckRequest) returns (HealthCheckResponse);
}
message HealthCheckRequest {} // deliberately empty - but still its own type
message HealthCheckResponse {
bool healthy = 1;
}Even an RPC that takes no input gets its own request message, empty if need be. That keeps every RPC's signature consistent, and it leaves room to add a field to the request later, such as an optional include_details flag on the health check, without changing the method itself. It is the same forward-compatibility reason as using input types for GraphQL mutations.
Well-Known Types: Don't Reinvent Timestamp
import "google/protobuf/timestamp.proto";
message Order {
int64 id = 1;
google.protobuf.Timestamp placed_at = 2; // standardized, not a raw int64 or string
}Protobuf ships a set of well-known types for common, easy-to-get-wrong shapes: Timestamp, Duration, Empty, and wrappers for nullable values. Using them instead of a home-made int64 placed_at_unix_seconds means every service represents a moment in time the same way, and the generated code in each language converts it consistently. The demo shows both ideas: the empty request growing a field without breaking old callers, and what happens when two services disagree about the unit of time.
Reaching for a well-known type before inventing your own representation for a common shape is the protobuf version of using a standard library data structure instead of hand-rolling one. It is more likely to be correct, and every engineer who touches the schema already understands it.
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.
Design Service Contracts 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.
No comments yet. Be the first to start the thread!