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.

Designing Service Contracts

3 min read

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

Two focused services instead of one do-everything service
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

A request or response with genuinely no fields still gets its own message type
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

Using protobuf's standard Timestamp instead of a bespoke representation
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.

Press Run: an old caller still works, and a seconds-versus-milliseconds mix-up is nonsense

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.

Ready to Build This?

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.

Sign In to ScaleDojo

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