08 Services

title: "Services in Protocol Buffers" description: "Define gRPC service endpoints in .proto files using the service keyword. Learn RPC method definitions, request/response message types, client streaming, server streaming, and bidirectional streaming." weight: 8 date: 2026-06-28 lastmod: 2026-06-28 tags: [api-development, grpc] }

Services in Protocol Buffers define the RPC endpoints that gRPC servers implement and clients call. A service contains one or more RPC methods, each with a request message type and a response message type.

What You'll Learn

• Service definition with the service keyword
• RPC method syntax and message types
• Unary, server-streaming, client-streaming, and bidirectional RPC signatures
• Service naming conventions and package organization
• Multiple services in one file

Why It Matters

The service definition is the API contract. It tells client and server developers exactly which methods exist and what data they exchange. Well-organized services make the API discoverable and maintainable.

Real-World Use

Google's Cloud Pub/Sub API defines services for Publisher and Subscriber. etcd uses a single KV service with methods for Put, Range, Delete, and Watch. gRPC health checking defines one service with one method.

flowchart TD
    Service[Service Definition] --> Method1[RPC Method 1]
    Service --> Method2[RPC Method 2]
    Method1 --> Request[Request Message]
    Method1 --> Response[Response Message]
    Method1 --> StreamType[Stream Type]
    StreamType --> Unary[Unary: request + response]
    StreamType --> ServerStream[Server Streaming: request, stream response]
    StreamType --> ClientStream[Client Streaming: stream request, response]
    StreamType --> Bidi[Bidirectional: stream request, stream response]

Teacher Mindset

Group related methods into one service. Each service represents a bounded capability. Use meaningful names that reflect the domain. Keep the number of methods per service manageable (5-15).

Code Examples

// Example 1: Service with all RPC types
service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);
  rpc ListOrders (ListOrdersRequest) returns (stream Order);
  rpc CreateOrder (stream CreateOrderRequest) returns (Order);
  rpc ProcessOrder (stream ProcessOrderRequest) returns (stream OrderStatus);
}

message GetOrderRequest {
  string order_id = 1;
}

message ListOrdersRequest {
  string customer_id = 1;
  int32 page_size = 2;
}

// Example 2: Multiple services in one package
package ecommerce;

service ProductService {
  rpc GetProduct (GetProductRequest) returns (Product);
  rpc ListProducts (ListProductsRequest) returns (stream Product);
  rpc CreateProduct (CreateProductRequest) returns (Product);
}

service InventoryService {
  rpc CheckStock (StockRequest) returns (StockResponse);
  rpc UpdateStock (stream StockUpdate) returns (StockSummary);
}

# Example 3: Generating server and client code
# Generate server code
protoc --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  proto/order_service.proto

# Generated files:
# order_service.pb.go  (message types)
# order_service_grpc.pb.go  (client and server stubs)

Common Mistakes

• Defining all methods in one giant service instead of splitting into focused services
• Using inconsistent RPC type patterns within a service
• Not including request/response messages for each method
• Forgetting to regenerate stubs after changing the service definition
• Ignoring proto package for service namespace management

Practice

1. Define a UserService with GetUser, ListUsers, UpdateUser methods.
2. Add a server-streaming method that returns a stream of active users.
3. Add a client-streaming method that accepts multiple create requests.
4. Add a bidirectional streaming method for real-time chat.
5. Challenge: Design a service hierarchy for an e-commerce platform with 3-4 services.

FAQ

Mini Project

Define three services for your order management system: OrderService (GetOrder, ListOrders, CreateOrder), PaymentService (ProcessPayment, RefundPayment), and NotificationService (SubscribeNotifications as bidirectional stream).

What's Next

Next, you will learn about the four gRPC RPC types: unary, server-streaming, client-streaming, and bidirectional streaming.