Part 6: API Documentation and Versioning in gRPC

The Undocumented API Nightmare

In 2021, I inherited a gRPC microservices project with 15 services and zero documentation. Every proto file was a cryptic mess of field numbers and abbreviated names. New team members took 2-3 weeks to understand the API contracts. Integration with external teams required endless Slack messages and Zoom calls.

The final straw? A partner integration that should have taken 2 days took 3 weeks because no one knew what fields were required, what the valid values were, or how error handling worked. That project delay cost approximately $40,000 in missed revenue.

This part covers everything about documenting and versioning gRPC APIs properly—lessons learned from managing 23 production services.

Protocol Buffer Documentation

Comprehensive Proto Comments

// protos/order/v1/order.proto
syntax = "proto3";

package order.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "common/types.proto";

/// OrderService manages customer orders in the e-commerce platform.
///
/// All methods require authentication via JWT token in metadata.
/// Rate limits apply per user: 100 requests/minute for read operations,
/// 10 requests/minute for write operations.
///
/// Support: [email protected]
/// SLA: 99.9% uptime
service OrderService {
  /// Creates a new order for a customer.
  ///
  /// This operation is idempotent when using the same idempotency_key.
  /// The order will be created with status PENDING and requires
  /// subsequent payment processing.
  ///
  /// Business Rules:
  /// - User must have valid billing address
  /// - All products must be in stock
  /// - Maximum 50 items per order
  /// - Total amount must not exceed $50,000 USD
  ///
  /// Error Codes:
  /// - INVALID_ARGUMENT: Invalid request parameters or missing required fields
  /// - NOT_FOUND: Product not found
  /// - FAILED_PRECONDITION: Insufficient stock, user not eligible
  /// - ALREADY_EXISTS: Order with same idempotency key exists
  /// - UNAUTHENTICATED: Missing or invalid authentication token
  /// - RESOURCE_EXHAUSTED: Rate limit exceeded
  ///
  /// Example:
  /// ```
  /// {
  ///   "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  ///   "user_id": "usr_123",
  ///   "items": [
  ///     {"product_id": "prod_456", "quantity": 2}
  ///   ],
  ///   "shipping_address": {
  ///     "street": "123 Main St",
  ///     "city": "San Francisco",
  ///     "state": "CA",
  ///     "postal_code": "94105",
  ///     "country": "US"
  ///   }
  /// }
  /// ```
  rpc CreateOrder(CreateOrderRequest) returns (Order);

  /// Retrieves an order by ID.
  ///
  /// Users can only retrieve their own orders unless they have
  /// the 'order:read:all' permission (admin/manager roles).
  ///
  /// Error Codes:
  /// - INVALID_ARGUMENT: Invalid order ID format
  /// - NOT_FOUND: Order not found
  /// - PERMISSION_DENIED: User doesn't have access to this order
  /// - UNAUTHENTICATED: Missing or invalid authentication token
  ///
  /// Performance: Average 50ms, P99 150ms
  rpc GetOrder(GetOrderRequest) returns (Order);

  /// Lists orders with filtering and pagination.
  ///
  /// Returns orders sorted by created_at DESC (newest first).
  /// Maximum page size is 100 items.
  ///
  /// Filtering:
  /// - By user_id: Required for non-admin users
  /// - By status: Optional status filter
  ///
  /// Error Codes:
  /// - INVALID_ARGUMENT: Invalid parameters (page_size > 100, etc.)
  /// - PERMISSION_DENIED: Non-admin user querying other users' orders
  /// - UNAUTHENTICATED: Missing or invalid authentication token
  ///
  /// Performance: Average 100ms, P99 300ms
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);

  /// Updates the status of an order.
  ///
  /// Requires 'order:update' permission (manager/admin only).
  ///
  /// Valid status transitions:
  /// - PENDING -> CONFIRMED, CANCELLED
  /// - CONFIRMED -> PROCESSING, CANCELLED
  /// - PROCESSING -> SHIPPED
  /// - SHIPPED -> DELIVERED
  /// - DELIVERED -> REFUNDED
  ///
  /// Error Codes:
  /// - INVALID_ARGUMENT: Invalid status value
  /// - NOT_FOUND: Order not found
  /// - FAILED_PRECONDITION: Invalid status transition
  /// - PERMISSION_DENIED: Insufficient permissions
  /// - UNAUTHENTICATED: Missing or invalid authentication token
  rpc UpdateOrderStatus(UpdateOrderStatusRequest) returns (Order);

  /// Cancels an order.
  ///
  /// Can only cancel orders in PENDING or CONFIRMED status.
  /// Users can cancel their own orders. Admins can cancel any order.
  ///
  /// This operation:
  /// - Restores product inventory
  /// - Triggers refund if payment was processed
  /// - Sends cancellation notification to user
  ///
  /// Error Codes:
  /// - NOT_FOUND: Order not found
  /// - FAILED_PRECONDITION: Order cannot be cancelled in current status
  /// - PERMISSION_DENIED: User doesn't have permission to cancel
  /// - UNAUTHENTICATED: Missing or invalid authentication token
  rpc CancelOrder(CancelOrderRequest) returns (Order);

  /// Streams real-time status updates for an order.
  ///
  /// Server streaming RPC that sends updates when order status changes.
  /// Stream automatically closes when order reaches terminal status
  /// (DELIVERED, CANCELLED, or REFUNDED).
  ///
  /// Typical update frequency: Every 30-60 seconds
  /// Maximum stream duration: 24 hours
  ///
  /// Error Codes:
  /// - NOT_FOUND: Order not found
  /// - PERMISSION_DENIED: User doesn't have access to this order
  /// - UNAUTHENTICATED: Missing or invalid authentication token
  rpc StreamOrderUpdates(StreamOrderUpdatesRequest) returns (stream OrderUpdate);
}

/// Represents a customer order
message Order {
  /// Unique order identifier.
  /// Format: "ord_" followed by 16 alphanumeric characters
  /// Example: "ord_a1b2c3d4e5f6g7h8"
  string id = 1;

  /// ID of the user who placed the order.
  /// Format: "usr_" followed by 16 alphanumeric characters
  /// Example: "usr_x1y2z3a4b5c6d7e8"
  string user_id = 2;

  /// Current status of the order.
  /// See OrderStatus enum for details.
  /// Default: ORDER_STATUS_PENDING
  OrderStatus status = 3;

  /// List of items in the order.
  /// Minimum: 1 item
  /// Maximum: 50 items
  repeated OrderItem items = 4;

  /// Shipping address for the order.
  /// Required field.
  common.v1.Address shipping_address = 5;

  /// Subtotal before tax and shipping.
  /// Sum of all item total_price values.
  common.v1.Money subtotal = 6;

  /// Tax amount.
  /// Calculated based on shipping address and local tax rates.
  common.v1.Money tax = 7;

  /// Shipping cost.
  /// Calculated based on weight, dimensions, and shipping method.
  common.v1.Money shipping_cost = 8;

  /// Total amount (subtotal + tax + shipping_cost).
  /// This is the amount charged to the customer.
  common.v1.Money total = 9;

  /// Timestamp when the order was created.
  /// Immutable after creation.
  google.protobuf.Timestamp created_at = 10;

  /// Timestamp when the order was last updated.
  /// Updated whenever any field changes.
  google.protobuf.Timestamp updated_at = 11;
}

/// Represents a single item within an order
message OrderItem {
  /// Unique item identifier (within the order).
  /// Generated by the system.
  string id = 1;

  /// ID of the product.
  /// Must reference a valid product in the catalog.
  string product_id = 2;

  /// Name of the product at time of order.
  /// Snapshot of product name (may differ from current product name).
  string product_name = 3;

  /// Quantity ordered.
  /// Minimum: 1
  /// Maximum: 100 per item
  int32 quantity = 4;

  /// Unit price at time of order.
  /// Snapshot of product price (may differ from current price).
  common.v1.Money unit_price = 5;

  /// Total price for this item (unit_price * quantity).
  /// Calculated field.
  common.v1.Money total_price = 6;
}

/// Order status values
enum OrderStatus {
  /// Default value. Should never be used.
  /// If you see this, there's a bug.
  ORDER_STATUS_UNSPECIFIED = 0;

  /// Order created but not yet confirmed.
  /// Awaiting payment or manual review.
  ORDER_STATUS_PENDING = 1;

  /// Order confirmed and payment received.
  /// Ready for processing.
  ORDER_STATUS_CONFIRMED = 2;

  /// Order is being prepared/packaged.
  /// Inventory has been reserved.
  ORDER_STATUS_PROCESSING = 3;

  /// Order has been shipped.
  /// Tracking information available.
  ORDER_STATUS_SHIPPED = 4;

  /// Order delivered to customer.
  /// Terminal status (unless refunded).
  ORDER_STATUS_DELIVERED = 5;

  /// Order cancelled by user or system.
  /// Inventory restored, refund issued if applicable.
  /// Terminal status.
  ORDER_STATUS_CANCELLED = 6;

  /// Order refunded after delivery.
  /// Payment reversed to customer.
  /// Terminal status.
  ORDER_STATUS_REFUNDED = 7;
}

/// Request to create a new order
message CreateOrderRequest {
  /// Idempotency key to prevent duplicate orders.
  /// Use a UUID v4 for uniqueness.
  /// Required field.
  /// Max length: 128 characters
  ///
  /// If a request with the same idempotency_key is received within 24 hours,
  /// the previously created order will be returned without creating a new one.
  ///
  /// Example: "550e8400-e29b-41d4-a716-446655440000"
  string idempotency_key = 1;

  /// ID of the user placing the order.
  /// Must match authenticated user unless caller has admin role.
  /// Required field.
  string user_id = 2;

  /// Items to include in the order.
  /// Required field.
  /// Minimum: 1 item
  /// Maximum: 50 items
  repeated CreateOrderItem items = 3;

  /// Shipping address for the order.
  /// Required field.
  /// Must be a valid, deliverable address.
  common.v1.Address shipping_address = 4;
}

/// Item to add to a new order
message CreateOrderItem {
  /// ID of the product to order.
  /// Must reference a valid, active product.
  /// Required field.
  string product_id = 1;

  /// Quantity to order.
  /// Required field.
  /// Minimum: 1
  /// Maximum: 100
  ///
  /// Quantity must not exceed available stock.
  int32 quantity = 2;
}

// ... Additional messages with similar documentation

Documentation Best Practices

1. Service-level comments: Purpose, authentication, rate limits, SLA

2. Method-level comments: Behavior, business rules, error codes, examples

3. Message-level comments: Purpose, constraints, relationships

4. Field-level comments: Format, validation rules, examples

5. Enum-level comments: Each value explained

Generating API Documentation

Using protoc-gen-doc

# Install protoc-gen-doc
go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest

# Generate HTML documentation
protoc \
  --plugin=protoc-gen-doc \
  --doc_out=./docs \
  --doc_opt=html,index.html \
  ./protos/**/*.proto

# Generate Markdown documentation
protoc \
  --plugin=protoc-gen-doc \
  --doc_out=./docs \
  --doc_opt=markdown,api.md \
  ./protos/**/*.proto

Custom Documentation Template

<!-- docs/template.html -->
<!DOCTYPE html>
<html>
<head>
  <title>{{.Title}}</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      max-width: 1200px;
      margin: 0 auto;
      padding: 20px;
    }
    .service {
      border-left: 4px solid #0066cc;
      padding-left: 20px;
      margin-bottom: 40px;
    }
    .method {
      background: #f5f5f5;
      padding: 15px;
      margin: 10px 0;
      border-radius: 5px;
    }
    .message {
      border: 1px solid #ddd;
      padding: 15px;
      margin: 10px 0;
    }
    code {
      background: #ffe6e6;
      padding: 2px 6px;
      border-radius: 3px;
    }
  </style>
</head>
<body>
  <h1>{{.Title}}</h1>
  
  {{range .Files}}
    <h2>{{.Name}}</h2>
    <p>{{.Description}}</p>
    
    {{range .Services}}
      <div class="service">
        <h3>{{.Name}}</h3>
        <p>{{.Description}}</p>
        
        {{range .Methods}}
          <div class="method">
            <h4>{{.Name}}</h4>
            <p>{{.Description}}</p>
            <p><strong>Request:</strong> <code>{{.RequestType}}</code></p>
            <p><strong>Response:</strong> <code>{{.ResponseType}}</code></p>
          </div>
        {{end}}
      </div>
    {{end}}
    
    {{range .Messages}}
      <div class="message">
        <h4>{{.LongName}}</h4>
        <p>{{.Description}}</p>
        <table>
          <tr>
            <th>Field</th>
            <th>Type</th>
            <th>Description</th>
          </tr>
          {{range .Fields}}
            <tr>
              <td><code>{{.Name}}</code></td>
              <td><code>{{.LongType}}</code></td>
              <td>{{.Description}}</td>
            </tr>
          {{end}}
        </table>
      </div>
    {{end}}
  {{end}}
</body>
</html>

Automated Documentation Generation

// scripts/generate-docs.ts
import { exec } from 'child_process';
import { promisify } from 'util';
import fs from 'fs/promises';
import path from 'path';

const execAsync = promisify(exec);

async function generateDocumentation() {
  const protoDir = './protos';
  const docsDir = './docs/api';

  // Create docs directory
  await fs.mkdir(docsDir, { recursive: true });

  // Generate HTML documentation
  console.log('Generating HTML documentation...');
  await execAsync(`
    protoc \
      --plugin=protoc-gen-doc \
      --doc_out=${docsDir} \
      --doc_opt=html,index.html \
      ${protoDir}/**/*.proto
  `);

  // Generate Markdown documentation
  console.log('Generating Markdown documentation...');
  await execAsync(`
    protoc \
      --plugin=protoc-gen-doc \
      --doc_out=${docsDir} \
      --doc_opt=markdown,api.md \
      ${protoDir}/**/*.proto
  `);

  // Generate JSON schema for API catalog
  console.log('Generating JSON schema...');
  await execAsync(`
    protoc \
      --plugin=protoc-gen-doc \
      --doc_out=${docsDir} \
      --doc_opt=json,schema.json \
      ${protoDir}/**/*.proto
  `);

  console.log('Documentation generated successfully!');
}

generateDocumentation().catch(console.error);

API Versioning Strategies

1. Package Versioning (Recommended)

// Version 1
// protos/order/v1/order.proto
syntax = "proto3";
package order.v1;

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

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

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

import "common/v2/types.proto";

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  // New method
  rpc BatchCreateOrders(BatchCreateOrdersRequest) returns (BatchCreateOrdersResponse);
}

message Order {
  string id = 1;
  string user_id = 2;
  // Changed: double -> Money type
  common.v2.Money total = 3;
  // New fields
  common.v2.Money tax = 4;
  OrderMetadata metadata = 5;
}

message OrderMetadata {
  string source = 1;
  map<string, string> tags = 2;
}

Server Supporting Multiple Versions

// src/grpc/server.ts
import * as grpc from '@grpc/grpc-js';
import { OrderServiceService as OrderServiceV1 } from '@generated/order/v1/order';
import { OrderServiceService as OrderServiceV2 } from '@generated/order/v2/order';
import { OrderHandlerV1 } from './handlers/v1/order.handler';
import { OrderHandlerV2 } from './handlers/v2/order.handler';

export class GrpcServer {
  private server: grpc.Server;

  constructor() {
    this.server = new grpc.Server();
    this.registerServices();
  }

  private registerServices(): void {
    // Register v1 handlers
    const orderHandlerV1 = new OrderHandlerV1();
    this.server.addService(OrderServiceV1, orderHandlerV1);

    // Register v2 handlers
    const orderHandlerV2 = new OrderHandlerV2();
    this.server.addService(OrderServiceV2, orderHandlerV2);

    logger.info('Registered services', {
      versions: ['v1', 'v2'],
    });
  }
}

Client Choosing Version

// Client connecting to v1
import { OrderServiceClient } from '@generated/order/v1/order';

const clientV1 = new OrderServiceClient(
  'localhost:50051',
  grpc.credentials.createInsecure()
);

// Client connecting to v2
import { OrderServiceClient as OrderServiceClientV2 } from '@generated/order/v2/order';

const clientV2 = new OrderServiceClientV2(
  'localhost:50051',
  grpc.credentials.createInsecure()
);

2. Field Versioning (Backward Compatible)

message Order {
  string id = 1;
  string user_id = 2;
  
  // Deprecated field (keep for backward compatibility)
  double total_amount = 3 [deprecated = true];
  
  // New field (preferred)
  common.v1.Money total = 4;
  
  // Fields added in v2 (optional, backward compatible)
  common.v1.Money tax = 5;
  OrderMetadata metadata = 6;
}

3. Method Versioning

service OrderService {
  // Original method
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  
  // V2 method with enhanced features
  rpc CreateOrderV2(CreateOrderV2Request) returns (OrderV2Response);
  
  // V3 method (latest)
  rpc CreateOrderV3(CreateOrderV3Request) returns (OrderV3Response);
}

Migration Strategies

Gradual Migration Pattern

// src/services/order.service.ts
export class OrderService {
  // Support both v1 and v2 internally
  async createOrder(
    request: CreateOrderRequestV1 | CreateOrderRequestV2,
    version: 'v1' | 'v2'
  ): Promise<Order> {
    // Normalize to v2 format internally
    const normalizedRequest = version === 'v1' 
      ? this.convertV1ToV2(request as CreateOrderRequestV1)
      : request as CreateOrderRequestV2;

    // Process using v2 logic
    const order = await this.processOrderV2(normalizedRequest);

    // Return in requested format
    return version === 'v1'
      ? this.convertV2ToV1(order)
      : order;
  }

  private convertV1ToV2(v1: CreateOrderRequestV1): CreateOrderRequestV2 {
    return {
      userId: v1.userId,
      items: v1.items,
      shippingAddress: v1.shippingAddress,
      // Set defaults for new v2 fields
      metadata: {
        source: 'legacy-v1',
        tags: {},
      },
    };
  }

  private convertV2ToV1(v2: Order): OrderV1 {
    return {
      id: v2.id,
      userId: v2.userId,
      items: v2.items,
      // Convert Money to simple double
      totalAmount: v2.total.units + (v2.total.nanos / 1e9),
      createdAt: v2.createdAt,
      updatedAt: v2.updatedAt,
      // Omit v2-only fields
    };
  }
}

Deprecation Headers

// src/grpc/handlers/v1/order.handler.ts
import * as grpc from '@grpc/grpc-js';

export class OrderHandlerV1 {
  async createOrder(
    call: grpc.ServerUnaryCall<CreateOrderRequest, Order>,
    callback: grpc.sendUnaryData<Order>
  ): Promise<void> {
    // Add deprecation warning in metadata
    const responseMetadata = new grpc.Metadata();
    responseMetadata.add('X-API-Warning', 'API v1 is deprecated. Please migrate to v2 by 2024-12-31.');
    responseMetadata.add('X-API-Version', '1');
    responseMetadata.add('X-API-Latest-Version', '2');
    responseMetadata.add('X-API-Sunset-Date', '2024-12-31');
    
    call.sendMetadata(responseMetadata);

    // Process request
    try {
      const order = await this.orderService.createOrder(call.request, 'v1');
      callback(null, order);
    } catch (error) {
      callback(error as any);
    }
  }
}

Breaking Change Checklist

Safe Changes (Backward Compatible)

✅ Adding new fields to messages

message Order {
  string id = 1;
  string user_id = 2;
  // Safe to add
  string notes = 3;
}

✅ Adding new methods to services

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  // Safe to add
  rpc GetOrderHistory(GetOrderHistoryRequest) returns (OrderHistoryResponse);
}

✅ Adding new enum values

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  // Safe to add
  ORDER_STATUS_ON_HOLD = 2;
}

✅ Making required fields optional

// Before
message CreateOrderRequest {
  string user_id = 1;  // Required
}

// After (backward compatible)
message CreateOrderRequest {
  string user_id = 1;  // Now optional, defaults to ""
}

Breaking Changes (Require New Version)

❌ Deleting fields

message Order {
  string id = 1;
  // BREAKING: Removed user_id field
  double total = 3;
}

❌ Changing field types

message Order {
  string id = 1;
  // BREAKING: Changed from double to Money
  common.v1.Money total = 3;
}

❌ Reusing field numbers

message Order {
  string id = 1;
  // BREAKING: Reused field number 2
  string order_number = 2;  // Was user_id before
}

❌ Renaming fields or messages

// BREAKING: Renamed CreateOrderRequest to PlaceOrderRequest
message PlaceOrderRequest {
  string user_id = 1;
}

❌ Changing method signatures

service OrderService {
  // BREAKING: Changed request/response types
  rpc CreateOrder(NewCreateOrderRequest) returns (NewOrderResponse);
}

Version Sunset Policy

// src/config/version-policy.ts
export interface VersionInfo {
  version: string;
  status: 'active' | 'deprecated' | 'sunset';
  releaseDate: Date;
  deprecationDate?: Date;
  sunsetDate?: Date;
  migrationGuideUrl?: string;
}

export const versionPolicy: Record<string, VersionInfo> = {
  v1: {
    version: 'v1',
    status: 'deprecated',
    releaseDate: new Date('2022-01-01'),
    deprecationDate: new Date('2023-06-01'),
    sunsetDate: new Date('2024-12-31'),
    migrationGuideUrl: 'https://docs.company.com/migration/v1-to-v2',
  },
  v2: {
    version: 'v2',
    status: 'active',
    releaseDate: new Date('2023-06-01'),
  },
};

// Log version usage for migration planning
export function logVersionUsage(
  version: string,
  method: string,
  userId?: string
): void {
  const info = versionPolicy[version];
  
  if (info?.status === 'deprecated') {
    logger.warn('Deprecated API version used', {
      version,
      method,
      userId,
      sunsetDate: info.sunsetDate,
      migrationGuideUrl: info.migrationGuideUrl,
    });
  }
}

Changelog and Release Notes

CHANGELOG.md

# API Changelog

All notable changes to the gRPC API will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [v2.1.0] - 2024-01-15

### Added
- New `BatchCreateOrders` method for creating multiple orders in one call
- `OrderMetadata` message for storing order source and tags
- `priority` field to `Order` message for express orders

### Changed
- `ListOrders` now supports filtering by date range
- Increased maximum page size from 50 to 100

### Deprecated
- `total_amount` field in `Order` (use `total` Money type instead)

### Fixed
- Incorrect tax calculation for international orders
- Race condition in concurrent order updates

## [v2.0.0] - 2023-06-01

### Added
- Version 2 of OrderService with breaking changes
- Money type for precise currency handling
- Enhanced error details with field-level validation

### Changed
- **BREAKING**: `total_amount` changed from `double` to `Money` type
- **BREAKING**: `CreateOrder` now requires `idempotency_key`

### Removed
- **BREAKING**: Removed deprecated `total_price` field

### Migration Guide
See: https://docs.company.com/migration/v1-to-v2

## [v1.5.0] - 2023-01-10

### Added
- `CancelOrder` method
- `StreamOrderUpdates` for real-time status updates

### Deprecated
- `total_amount` will be replaced with `Money` type in v2.0

## [v1.0.0] - 2022-01-01

Initial release

Documentation Website

Using Docusaurus

npx create-docusaurus@latest api-docs classic
cd api-docs

# Add API documentation
cp ../docs/api.md docs/api-reference.md

# Configure sidebar

// api-docs/sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['introduction', 'quick-start', 'authentication'],
    },
    {
      type: 'category',
      label: 'API Reference',
      items: [
        'api-reference',
        'order-service',
        'product-service',
        'user-service',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      items: [
        'error-handling',
        'pagination',
        'versioning',
        'best-practices',
      ],
    },
    {
      type: 'category',
      label: 'Migration',
      items: ['v1-to-v2-migration', 'changelog'],
    },
  ],
};

Key Takeaways

1. Document Everything: Comments in proto files are your API contract

2. Version Properly: Use package versioning for breaking changes

3. Support Multiple Versions: Run v1 and v2 simultaneously during migration

4. Communicate Changes: Changelog, deprecation warnings, migration guides

5. Plan Sunsets: Give clients 6-12 months to migrate

6. Never Break Silently: Use proper versioning, not silent breaking changes

7. Automate Docs: Generate documentation from proto files

My $40,000 Lesson: Good documentation pays for itself in reduced integration time and support costs.

---

Next: Part 7: Testing, Performance, and Production Deployment

Series Navigation: gRPC 101 Series