gRPC API Versioning Across Services
On this page
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:
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
// 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).
Running v1 and v2 side by side
Keep one implementation and one data model, with thin adapters per version:
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
.protofiles that drift. - Owners per package review changes (CODEOWNERS), since a change affects every caller.
- Breaking-change policy:
FILErules for packages others compile against, with explicit exceptions for planned removals (Day 13).
Retiring an old gRPC API version
- Mark the old service or methods
option deprecated = true;and announce a timeline. - Measure who still calls it: per-method metrics with caller identity (Day 24) show exactly which services and client versions remain.
- Help callers migrate; contact them directly.
- 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.