Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 4 · Lesson 23 · 3 min read

gRPC API Versioning Across Services

On this page
  1. Evolve first, version rarely
  2. gRPC API versions in the package name
  3. Running v1 and v2 side by side
  4. Sharing .proto files between teams
  5. Retiring an old gRPC API version
  6. Check yourself

Evolve first, version rarely

Protobuf's compatibility rules (Day 12) mean most changes need no new version at all: add fields, add RPCs, add enum values, deprecate instead of delete. buf breaking in CI enforces this:

Code
buf breaking --against '.git#branch=main'

A new version is only for changes that can't be made compatibly: restructuring messages, changing semantics, removing RPCs.

gRPC API versions in the package name

Protobuf
// proto/catalog/v1/catalog.proto
package catalog.v1;
service CatalogService {
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
}

// proto/catalog/v2/catalog.proto
package catalog.v2;
service CatalogService {
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);   // new, incompatible shape
}

The full method names differ (/catalog.v1.CatalogService/GetProduct versus /catalog.v2.CatalogService/GetProduct), so one server can register both services and serve old and new clients at once. buf's lint rules require the version suffix (PACKAGE_VERSION_SUFFIX), and the course's lint run flagged a package without one (Day 2).

Compatible changes evolve a package in place, checked by buf breaking; incompatible redesigns become a new package version served alongside the old one until clients migrate.
Compatible changes evolve a package in place, checked by buf breaking; incompatible redesigns become a new package version served alongside the old one until clients migrate.

Running v1 and v2 side by side

Keep one implementation and one data model, with thin adapters per version:

GraphQL
type catalogV2 struct{ catalogv2.UnimplementedCatalogServiceServer; core *Catalog }
type catalogV1 struct{ catalogv1.UnimplementedCatalogServiceServer; core *Catalog }

func (s catalogV1) GetProduct(ctx context.Context, req *catalogv1.GetProductRequest) (*catalogv1.GetProductResponse, error) {
	p, err := s.core.Get(ctx, req.GetId())
	if err != nil {
		return nil, err
	}
	return toV1(p), nil   // map the current model to the old shape
}

catalogv1.RegisterCatalogServiceServer(srv, catalogV1{core: c})
catalogv2.RegisterCatalogServiceServer(srv, catalogV2{core: c})

Bug fixes reach both versions; only the translation layer is duplicated.

Sharing .proto files between teams

  • One schema repository (or the Buf Schema Registry) holds every service's protos, with lint and breaking checks on each change, and versioned generated packages per language.
  • Consumers depend on published packages, not copied .proto files that drift.
  • Owners per package review changes (CODEOWNERS), since a change affects every caller.
  • Breaking-change policy: FILE rules for packages others compile against, with explicit exceptions for planned removals (Day 13).

Retiring an old gRPC API version

  1. Mark the old service or methods option deprecated = true; and announce a timeline.
  2. Measure who still calls it: per-method metrics with caller identity (Day 24) show exactly which services and client versions remain.
  3. Help callers migrate; contact them directly.
  4. Remove the old registration once traffic reaches zero, then delete the old package.

Mobile apps are the slowest to migrate: old app versions may call v1 for years, so plan longer support windows or force-upgrade policies for them.

Check yourself

Only for changes that can't be made compatibly, such as restructuring messages, removing RPCs or changing the meaning of fields. Most changes, like adding fields or RPCs, belong in the existing version.

Register both services on the same server; their fully qualified method names differ by package, like orders.v1.OrderService and orders.v2.OrderService. Both can be thin adapters over one shared core implementation.

Per-method metrics broken down by caller show when no clients still call it. Announce a deadline, contact remaining callers, and remove it once traffic reaches zero.

Through a central schema repository or registry like the Buf Schema Registry, with versioned modules and generated packages per language.