Part 2: gRPC Service Design Patterns and Best Practices

The $30,000 Design Mistake

In early 2022, I designed a gRPC service for our payment processing system. I thought, "It's just like REST but with protobuf." I was wrong. Three months into production, we faced:

• Breaking changes every week (clients constantly breaking)

• Performance degradation (fetching nested data required 12+ RPC calls)

• Maintenance nightmare (200+ proto files with duplicated messages)

The redesign took 6 weeks and cost approximately $30,000 in engineering time. This part contains everything I learned so you don't make the same mistakes.

Resource-Oriented Design in gRPC

The Mindset Shift

// ❌ BAD: RPC-oriented (what I did initially)
service OrderOperations {
  rpc DoCreateOrder(CreateParams) returns (OrderResult);
  rpc DoUpdateOrder(UpdateParams) returns (UpdateResult);
  rpc DoDeleteOrder(DeleteParams) returns (DeleteResult);
  rpc DoGetOrder(GetParams) returns (OrderData);
}

// ✅ GOOD: Resource-oriented (what I should have done)
service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  rpc UpdateOrder(UpdateOrderRequest) returns (Order);
  rpc DeleteOrder(DeleteOrderRequest) returns (google.protobuf.Empty);
}

Why Resource-Oriented?

• Consistent patterns across all services

• Easier to understand and maintain

• Maps well to database operations

• Follows Google's API design guide

Standard Methods Pattern

syntax = "proto3";

package ecommerce.v1;

import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

// Resource definition
message Product {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  int32 stock_quantity = 5;
  string category_id = 6;
  ProductStatus status = 7;
  google.protobuf.Timestamp created_at = 8;
  google.protobuf.Timestamp updated_at = 9;
}

enum ProductStatus {
  PRODUCT_STATUS_UNSPECIFIED = 0;
  PRODUCT_STATUS_ACTIVE = 1;
  PRODUCT_STATUS_DISCONTINUED = 2;
  PRODUCT_STATUS_OUT_OF_STOCK = 3;
}

// Standard CRUD service
service ProductService {
  // Get a single product
  rpc GetProduct(GetProductRequest) returns (Product);
  
  // List products with filtering, sorting, pagination
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
  
  // Create a new product
  rpc CreateProduct(CreateProductRequest) returns (Product);
  
  // Update a product (full or partial)
  rpc UpdateProduct(UpdateProductRequest) returns (Product);
  
  // Delete a product
  rpc DeleteProduct(DeleteProductRequest) returns (google.protobuf.Empty);
}

// Get single resource
message GetProductRequest {
  string id = 1;
}

// List resources with pagination
message ListProductsRequest {
  // Pagination
  int32 page_size = 1;  // Max 100
  string page_token = 2; // From previous response
  
  // Filtering
  string category_id = 3;
  ProductStatus status = 4;
  double min_price = 5;
  double max_price = 6;
  
  // Sorting
  string order_by = 7;  // "price", "-price" (desc), "created_at"
}

message ListProductsResponse {
  repeated Product products = 1;
  string next_page_token = 2;
  int32 total_count = 3;
}

// Create resource
message CreateProductRequest {
  Product product = 1;
}

// Update resource with field mask
message UpdateProductRequest {
  Product product = 1;
  google.protobuf.FieldMask update_mask = 2;
}

// Delete resource
message DeleteProductRequest {
  string id = 1;
}

My Production Implementation

import { ServerUnaryCall, sendUnaryData } from '@grpc/grpc-js';
import { Product, ListProductsRequest, ListProductsResponse } from './generated/product';

class ProductServiceImpl {
  // Get single product
  async getProduct(
    call: ServerUnaryCall<GetProductRequest, Product>,
    callback: sendUnaryData<Product>
  ): Promise<void> {
    try {
      const { id } = call.request;
      
      const product = await this.productRepository.findById(id);
      
      if (!product) {
        return callback({
          code: grpc.status.NOT_FOUND,
          message: `Product ${id} not found`,
        });
      }
      
      callback(null, product);
    } catch (error) {
      callback({
        code: grpc.status.INTERNAL,
        message: 'Failed to fetch product',
      });
    }
  }

  // List products with filtering and pagination
  async listProducts(
    call: ServerUnaryCall<ListProductsRequest, ListProductsResponse>,
    callback: sendUnaryData<ListProductsResponse>
  ): Promise<void> {
    try {
      const { 
        pageSize = 10, 
        pageToken, 
        categoryId, 
        status,
        minPrice,
        maxPrice,
        orderBy 
      } = call.request;
      
      // Validate page size
      const limit = Math.min(pageSize, 100);
      
      // Build query
      const query: any = {};
      
      if (categoryId) query.categoryId = categoryId;
      if (status) query.status = status;
      if (minPrice !== undefined || maxPrice !== undefined) {
        query.price = {};
        if (minPrice !== undefined) query.price.$gte = minPrice;
        if (maxPrice !== undefined) query.price.$lte = maxPrice;
      }
      
      // Parse cursor-based pagination
      let offset = 0;
      if (pageToken) {
        offset = parseInt(Buffer.from(pageToken, 'base64').toString('utf-8'));
      }
      
      // Execute query
      const [products, total] = await Promise.all([
        this.productRepository.find(query, {
          limit,
          offset,
          orderBy: orderBy || 'created_at',
        }),
        this.productRepository.count(query),
      ]);
      
      // Generate next page token
      const nextPageToken = products.length === limit
        ? Buffer.from((offset + limit).toString()).toString('base64')
        : '';
      
      callback(null, {
        products,
        nextPageToken,
        totalCount: total,
      });
    } catch (error) {
      callback({
        code: grpc.status.INTERNAL,
        message: 'Failed to list products',
      });
    }
  }

  // Update with field mask
  async updateProduct(
    call: ServerUnaryCall<UpdateProductRequest, Product>,
    callback: sendUnaryData<Product>
  ): Promise<void> {
    try {
      const { product, updateMask } = call.request;
      
      // Get existing product
      const existing = await this.productRepository.findById(product.id);
      if (!existing) {
        return callback({
          code: grpc.status.NOT_FOUND,
          message: `Product ${product.id} not found`,
        });
      }
      
      // Apply field mask (only update specified fields)
      const fieldsToUpdate = updateMask?.paths || [];
      const updates: any = {};
      
      for (const field of fieldsToUpdate) {
        if (product[field] !== undefined) {
          updates[field] = product[field];
        }
      }
      
      // Update timestamp
      updates.updatedAt = new Date();
      
      const updated = await this.productRepository.update(product.id, updates);
      
      callback(null, updated);
    } catch (error) {
      callback({
        code: grpc.status.INTERNAL,
        message: 'Failed to update product',
      });
    }
  }
}

Message Design Best Practices

1. Use Proper Naming Conventions

// ✅ GOOD: Clear, descriptive names
message CreateOrderRequest {
  string user_id = 1;
  repeated OrderItem items = 2;
  ShippingAddress shipping_address = 3;
}

message Order {
  string id = 1;
  string user_id = 2;
  OrderStatus status = 3;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;  // Always have UNSPECIFIED
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_CONFIRMED = 2;
  ORDER_STATUS_SHIPPED = 3;
}

// ❌ BAD: Unclear, abbreviated names
message CreateOrdReq {
  string uid = 1;
  repeated Item itms = 2;
  Addr addr = 3;
}

message Ord {
  string i = 1;
  string u = 2;
  int32 s = 3;  // What is 's'? Status? State?
}

My Naming Rules:

• Messages: PascalCase (CreateOrderRequest)

• Fields: snake_case (user_id, shipping_address)

• Enums: UPPER_SNAKE_CASE with prefix (ORDER_STATUS_PENDING)

• Services: PascalCase with "Service" suffix (OrderService)

• RPCs: PascalCase, verb-based (GetOrder, CreateOrder)

2. Design for Evolution

// Version 1 - Initial design
message Order {
  string id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  double total_amount = 4;
}

// Version 2 - Adding optional fields (backward compatible!)
message Order {
  string id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  double total_amount = 4;
  
  // New fields - old clients ignore these
  string discount_code = 5;
  double discount_amount = 6;
  TaxDetails tax_details = 7;
  repeated string notes = 8;
}

// ❌ NEVER DO THIS - Breaking changes!
message Order {
  string id = 1;
  string user_id = 2;
  // REMOVED: repeated OrderItem items = 3;  // DON'T DELETE FIELDS!
  // CHANGED TYPE: string total_amount = 4;  // DON'T CHANGE TYPES!
}

The Golden Rules I Follow:

1. Never delete fields - Mark as deprecated instead

2. Never reuse field numbers - Ever!

3. Never change field types - Add new fields instead

4. Add, don't modify - Always additive changes

3. Use Nested Messages Wisely

// ✅ GOOD: Reusable nested messages
message Address {
  string street = 1;
  string city = 2;
  string state = 3;
  string postal_code = 4;
  string country = 5;
}

message User {
  string id = 1;
  string name = 2;
  Address billing_address = 3;
  Address shipping_address = 4;  // Reusing Address
}

message Order {
  string id = 1;
  string user_id = 2;
  Address shipping_address = 3;  // Same Address type
}

// ❌ BAD: Duplication
message User {
  string id = 1;
  string name = 2;
  
  // Duplicated address structure
  message BillingAddress {
    string street = 1;
    string city = 2;
    string state = 3;
  }
  BillingAddress billing_address = 3;
  
  // Duplicated again!
  message ShippingAddress {
    string street = 1;
    string city = 2;
    string state = 3;
  }
  ShippingAddress shipping_address = 4;
}

4. Handle Optional Fields Correctly

import "google/protobuf/wrappers.proto";

// Problem: Can't distinguish between "not set" and "default value"
message UserUpdate {
  string name = 1;          // "" if not set OR if actually empty
  int32 age = 2;            // 0 if not set OR if actually 0
  bool verified = 3;        // false if not set OR if actually false
}

// ✅ Solution 1: Use wrapper types
message UserUpdate {
  google.protobuf.StringValue name = 1;    // null if not set
  google.protobuf.Int32Value age = 2;      // null if not set
  google.protobuf.BoolValue verified = 3;  // null if not set
}

// ✅ Solution 2: Use field mask
message UpdateUserRequest {
  User user = 1;
  google.protobuf.FieldMask update_mask = 2;  // Specifies which fields to update
}

Production Story: I had a bug where users couldn't reset their age to 0 (baby?). The system thought "0 = not set" and ignored the update. Wrapper types fixed it.

5. Use Appropriate Data Types

message Order {
  // ✅ Use string for IDs (UUIDs, MongoDB ObjectIds)
  string id = 1;  // "ord_1234567890"
  
  // ✅ Use int64 for timestamps (Unix milliseconds)
  int64 created_at = 2;  // 1704931200000
  
  // ✅ Or use Timestamp for better semantics
  google.protobuf.Timestamp created_at = 3;
  
  // ✅ Use double for money (or dedicated Money type)
  double amount = 4;  // Be careful with floating point!
  
  // ✅ Better: Use custom Money type
  Money total = 5;
  
  // ✅ Use bytes for binary data
  bytes signature = 6;
  
  // ✅ Use enum for fixed set of values
  OrderStatus status = 7;
  
  // ❌ Don't use float for money (precision issues!)
  float price = 8;  // BAD!
}

// Money type (from Google's API design guide)
message Money {
  string currency_code = 1;  // "USD", "EUR"
  int64 units = 2;           // Dollar amount
  int32 nanos = 3;           // Cents (0-999,999,999)
}

Real Bug: Used float for prices. A $19.99 item became $19.989999... in the database. Customers complained. Learned my lesson.

Pagination Patterns

Cursor-Based Pagination (My Preferred Method)

message ListOrdersRequest {
  int32 page_size = 1;    // Max 100
  string page_token = 2;  // Opaque cursor from previous response
  
  // Optional filters
  string user_id = 3;
  OrderStatus status = 4;
}

message ListOrdersResponse {
  repeated Order orders = 1;
  string next_page_token = 2;  // Empty if no more results
  int32 total_count = 3;       // Optional: total matching items
}

TypeScript Implementation:

interface Cursor {
  lastId: string;
  lastCreatedAt: number;
}

async function listOrders(
  request: ListOrdersRequest
): Promise<ListOrdersResponse> {
  const limit = Math.min(request.pageSize || 10, 100);
  
  // Decode cursor
  let cursor: Cursor | null = null;
  if (request.pageToken) {
    const decoded = Buffer.from(request.pageToken, 'base64').toString('utf-8');
    cursor = JSON.parse(decoded);
  }
  
  // Build query
  const query: any = {};
  if (request.userId) query.userId = request.userId;
  if (request.status) query.status = request.status;
  
  // Add cursor condition
  if (cursor) {
    query.$or = [
      { createdAt: { $lt: cursor.lastCreatedAt } },
      { 
        createdAt: cursor.lastCreatedAt, 
        id: { $gt: cursor.lastId } 
      }
    ];
  }
  
  // Fetch one extra to check if there are more results
  const orders = await db.orders
    .find(query)
    .sort({ createdAt: -1, id: 1 })
    .limit(limit + 1)
    .toArray();
  
  // Check if there are more results
  const hasMore = orders.length > limit;
  if (hasMore) {
    orders.pop(); // Remove the extra item
  }
  
  // Generate next page token
  let nextPageToken = '';
  if (hasMore && orders.length > 0) {
    const lastOrder = orders[orders.length - 1];
    const nextCursor: Cursor = {
      lastId: lastOrder.id,
      lastCreatedAt: lastOrder.createdAt,
    };
    nextPageToken = Buffer.from(JSON.stringify(nextCursor)).toString('base64');
  }
  
  // Get total count (expensive, use cache)
  const totalCount = await this.getCachedCount(query);
  
  return {
    orders,
    nextPageToken,
    totalCount,
  };
}

Why Cursor-Based?

• Consistent results even if data changes

• Performance doesn't degrade with deep pages

• No "page 1000" problem

Offset-Based Pagination (Simple Use Cases)

message ListProductsRequest {
  int32 page_size = 1;
  int32 page_number = 2;  // 1-based
}

message ListProductsResponse {
  repeated Product products = 1;
  int32 total_count = 2;
  int32 total_pages = 3;
  int32 current_page = 4;
}

Use When: Data is relatively static, users need to jump to specific pages.

Filtering and Searching

Structured Filtering

message ListOrdersRequest {
  int32 page_size = 1;
  string page_token = 2;
  
  // Structured filters
  OrderFilter filter = 3;
  string order_by = 4;  // "created_at", "-total_amount"
}

message OrderFilter {
  // Single value filters
  string user_id = 1;
  OrderStatus status = 2;
  
  // Range filters
  DateRange created_at = 3;
  AmountRange total_amount = 4;
  
  // Array filters
  repeated string product_ids = 5;  // Orders containing any of these products
}

message DateRange {
  google.protobuf.Timestamp start = 1;
  google.protobuf.Timestamp end = 2;
}

message AmountRange {
  double min = 1;
  double max = 2;
}

Full-Text Search

message SearchProductsRequest {
  string query = 1;           // Search text
  int32 page_size = 2;
  string page_token = 3;
  
  // Optional refinements
  repeated string category_ids = 4;
  PriceRange price_range = 5;
}

message SearchProductsResponse {
  repeated ProductResult results = 1;
  string next_page_token = 2;
  int32 total_count = 3;
}

message ProductResult {
  Product product = 1;
  double relevance_score = 2;  // 0.0 to 1.0
  repeated string matched_fields = 3;  // ["name", "description"]
}

My Implementation (using Elasticsearch):

async function searchProducts(
  request: SearchProductsRequest
): Promise<SearchProductsResponse> {
  const { query, pageSize = 10, categoryIds, priceRange } = request;
  
  // Build Elasticsearch query
  const esQuery = {
    bool: {
      must: [
        {
          multi_match: {
            query,
            fields: ['name^3', 'description^2', 'tags'],
            type: 'best_fields',
            fuzziness: 'AUTO',
          },
        },
      ],
      filter: [],
    },
  };
  
  // Add category filter
  if (categoryIds && categoryIds.length > 0) {
    esQuery.bool.filter.push({
      terms: { category_id: categoryIds },
    });
  }
  
  // Add price range filter
  if (priceRange) {
    esQuery.bool.filter.push({
      range: {
        price: {
          gte: priceRange.min,
          lte: priceRange.max,
        },
      },
    });
  }
  
  // Execute search
  const response = await esClient.search({
    index: 'products',
    body: {
      query: esQuery,
      size: pageSize,
      from: parsePageToken(request.pageToken),
    },
  });
  
  // Map results
  const results = response.hits.hits.map(hit => ({
    product: hit._source,
    relevanceScore: hit._score / response.hits.max_score, // Normalize
    matchedFields: Object.keys(hit.highlight || {}),
  }));
  
  return {
    results,
    nextPageToken: generatePageToken(results.length),
    totalCount: response.hits.total.value,
  };
}

Error Handling Patterns

Rich Error Details

// Use google.rpc.Status for rich errors
import "google/rpc/status.proto";
import "google/rpc/error_details.proto";

message CreateOrderResponse {
  oneof result {
    Order order = 1;
    google.rpc.Status error = 2;
  }
}

TypeScript Implementation:

import * as grpc from '@grpc/grpc-js';
import { Status } from 'grpc-status-details-serializer';

async function createOrder(
  call: ServerUnaryCall<CreateOrderRequest, Order>,
  callback: sendUnaryData<Order>
): Promise<void> {
  try {
    const { userId, items } = call.request;
    
    // Validation
    if (!items || items.length === 0) {
      const status = new Status(
        grpc.status.INVALID_ARGUMENT,
        'Order must contain at least one item',
        [
          {
            '@type': 'type.googleapis.com/google.rpc.BadRequest',
            fieldViolations: [
              {
                field: 'items',
                description: 'Items array cannot be empty',
              },
            ],
          },
        ]
      );
      
      return callback(status as any);
    }
    
    // Business logic
    const order = await this.orderService.create(userId, items);
    
    callback(null, order);
  } catch (error) {
    // Handle different error types
    if (error instanceof InsufficientStockError) {
      const status = new Status(
        grpc.status.FAILED_PRECONDITION,
        'Insufficient stock for one or more items',
        [
          {
            '@type': 'type.googleapis.com/google.rpc.PreconditionFailure',
            violations: error.violations.map(v => ({
              type: 'INSUFFICIENT_STOCK',
              subject: v.productId,
              description: `Requested: ${v.requested}, Available: ${v.available}`,
            })),
          },
        ]
      );
      
      return callback(status as any);
    }
    
    // Generic error
    callback({
      code: grpc.status.INTERNAL,
      message: 'Failed to create order',
    });
  }
}

Custom Error Messages

message OrderError {
  OrderErrorCode code = 1;
  string message = 2;
  map<string, string> details = 3;
}

enum OrderErrorCode {
  ORDER_ERROR_CODE_UNSPECIFIED = 0;
  ORDER_ERROR_CODE_INVALID_ITEMS = 1;
  ORDER_ERROR_CODE_INSUFFICIENT_STOCK = 2;
  ORDER_ERROR_CODE_PAYMENT_FAILED = 3;
  ORDER_ERROR_CODE_USER_NOT_FOUND = 4;
}

Versioning Strategies

1. Package Versioning (My Preferred)

// v1/order.proto
syntax = "proto3";
package ecommerce.order.v1;

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
}

message Order {
  string id = 1;
  string user_id = 2;
  double total_amount = 3;
}

// v2/order.proto (breaking changes in separate package)
syntax = "proto3";
package ecommerce.order.v2;

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
}

message Order {
  string id = 1;
  string user_id = 2;
  Money total_amount = 3;  // Changed from double to Money
  TaxDetails tax_details = 4;  // New field
}

Server Setup:

// Support both v1 and v2 simultaneously
import * as grpc from '@grpc/grpc-js';
import { OrderServiceV1 } from './generated/v1/order';
import { OrderServiceV2 } from './generated/v2/order';

const server = new grpc.Server();

// Register v1 handlers
server.addService(OrderServiceV1.service, new OrderServiceV1Impl());

// Register v2 handlers
server.addService(OrderServiceV2.service, new OrderServiceV2Impl());

server.bindAsync(
  '0.0.0.0:50051',
  grpc.ServerCredentials.createInsecure(),
  () => server.start()
);

2. Field Versioning

message Order {
  string id = 1;
  string user_id = 2;
  
  // Deprecated fields
  double total_amount = 3 [deprecated = true];  // Use total instead
  
  // New fields
  Money total = 4;  // Replaces total_amount
  TaxDetails tax_details = 5;
}

3. Method Versioning

service OrderService {
  // V1 methods
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  
  // V2 methods (new name, backward compatible)
  rpc CreateOrderV2(CreateOrderV2Request) returns (OrderV2);
}

Performance Optimization Patterns

1. Batch Operations

// Instead of N separate calls
rpc GetProduct(GetProductRequest) returns (Product);

// Use batch endpoint
rpc BatchGetProducts(BatchGetProductsRequest) returns (BatchGetProductsResponse);

message BatchGetProductsRequest {
  repeated string ids = 1;  // Max 100
}

message BatchGetProductsResponse {
  map<string, Product> products = 1;  // id -> Product
  repeated string not_found = 2;      // IDs that don't exist
}

Performance Impact (from my production):

• Individual calls: 100 products = 100 RPCs = 2.5s

• Batch call: 100 products = 1 RPC = 85ms (29x faster)

2. Field Masks

import "google/protobuf/field_mask.proto";

message GetOrderRequest {
  string id = 1;
  google.protobuf.FieldMask field_mask = 2;  // Specify which fields to return
}

Client Usage:

const order = await client.getOrder({
  id: 'ord_123',
  fieldMask: {
    paths: ['id', 'status', 'total_amount'],  // Only return these fields
  },
});

// Server only fetches and serializes requested fields
// Reduced payload size by 70% in my analytics service

3. Streaming for Large Datasets

// Instead of returning all results at once
rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);

// Stream results
rpc StreamOrders(StreamOrdersRequest) returns (stream Order);

When to Use:

• Large result sets (1000+ items)

• Real-time updates

• Progressive processing

Service Organization

Microservices Boundary Design

// ✅ GOOD: Single responsibility
// user-service/user.proto
service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc CreateUser(CreateUserRequest) returns (User);
  rpc UpdateUser(UpdateUserRequest) returns (User);
}

// order-service/order.proto
service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  rpc ListUserOrders(ListUserOrdersRequest) returns (ListUserOrdersResponse);
}

// product-service/product.proto
service ProductService {
  rpc GetProduct(GetProductRequest) returns (Product);
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
}

// ❌ BAD: God service
service EcommerceService {
  // Users
  rpc GetUser(GetUserRequest) returns (User);
  rpc CreateUser(CreateUserRequest) returns (User);
  
  // Orders
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  
  // Products
  rpc GetProduct(GetProductRequest) returns (Product);
  
  // Payments
  rpc ProcessPayment(PaymentRequest) returns (Payment);
  
  // Shipping
  rpc CalculateShipping(ShippingRequest) returns (ShippingRate);
  
  // ... 50 more methods
}

Shared Messages

// common/types.proto
syntax = "proto3";
package common.v1;

message Address {
  string street = 1;
  string city = 2;
  string state = 3;
  string postal_code = 4;
  string country = 5;
}

message Money {
  string currency_code = 1;
  int64 units = 2;
  int32 nanos = 3;
}

// user-service/user.proto
import "common/types.proto";

message User {
  string id = 1;
  string name = 2;
  common.v1.Address billing_address = 3;  // Reuse common type
}

// order-service/order.proto
import "common/types.proto";

message Order {
  string id = 1;
  common.v1.Money total = 2;  // Reuse common type
  common.v1.Address shipping_address = 3;
}

Idempotency

message CreateOrderRequest {
  string idempotency_key = 1;  // Client-generated unique key
  string user_id = 2;
  repeated OrderItem items = 3;
}

Server Implementation:

async function createOrder(
  request: CreateOrderRequest
): Promise<Order> {
  const { idempotencyKey, userId, items } = request;
  
  // Check if order with this idempotency key exists
  const existing = await this.idempotencyStore.get(idempotencyKey);
  if (existing) {
    return existing; // Return cached result
  }
  
  // Create new order
  const order = await this.orderService.create(userId, items);
  
  // Cache result for 24 hours
  await this.idempotencyStore.set(idempotencyKey, order, { ttl: 86400 });
  
  return order;
}

Why Critical: In my payment service, network issues caused duplicate charges. Idempotency keys prevented $15,000 in double charges over 6 months.

API Documentation

// Document everything!
syntax = "proto3";
package ecommerce.order.v1;

/// OrderService manages customer orders
/// Authentication: Required
/// Rate Limit: 1000 requests per minute
service OrderService {
  /// Creates a new order
  /// Idempotent: Yes (using idempotency_key)
  /// Errors:
  ///   - INVALID_ARGUMENT: Invalid items or missing required fields
  ///   - FAILED_PRECONDITION: Insufficient stock
  ///   - UNAUTHENTICATED: Missing or invalid authentication
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  
  /// Retrieves an order by ID
  /// Errors:
  ///   - NOT_FOUND: Order does not exist
  ///   - PERMISSION_DENIED: User doesn't have access to this order
  rpc GetOrder(GetOrderRequest) returns (Order);
}

/// Request to create a new order
message CreateOrderRequest {
  /// Unique key to ensure idempotency (UUID recommended)
  /// Max length: 128 characters
  string idempotency_key = 1;
  
  /// ID of the user placing the order
  /// Format: "usr_" followed by alphanumeric characters
  string user_id = 2;
  
  /// List of items to order
  /// Min: 1 item, Max: 100 items
  repeated OrderItem items = 3;
  
  /// Shipping address for the order
  Address shipping_address = 4;
}

/// Represents a customer order
message Order {
  /// Unique order identifier
  /// Format: "ord_" followed by alphanumeric characters
  string id = 1;
  
  /// Current status of the order
  OrderStatus status = 2;
  
  /// Total amount including taxes and shipping
  Money total = 3;
  
  /// Timestamp when order was created (Unix milliseconds)
  int64 created_at = 4;
}

Key Takeaways

1. Resource-Oriented Design: Think in resources (nouns), not operations (verbs)

2. Evolution > Perfection: Design for change, use field masks and versioning

3. Performance Matters: Use batch operations, streaming, and field selection

4. Error Handling: Provide rich error details for better debugging

5. Document Everything: Future you (and your team) will thank you

My Biggest Lesson: Spend time on design upfront. A week of design saves months of refactoring.

---

Next: Part 3: Building gRPC Services with TypeScript and Node.js

Series Navigation: gRPC 101 Series