Versioning gRPC APIs — Protocol Buffers Compatibility

In this tutorial, you will learn about Versioning gRPC APIs. We cover key concepts, practical examples, and best practices to help you master this topic.

gRPC uses Protocol Buffers for service definitions with built-in compatibility rules that enable additive changes without breaking existing clients.

Protocol Buffer Rules

Never change field numbers. Never remove fields (use reserved). New fields are optional for existing clients. Use package-based versioning for major changes.

Best Practices

// Package-based versioning
package dodatech.users.v1;

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
}

message User {
  int32 id = 1;
  string name = 2;
  // Deprecated: use display_name instead
  string full_name = 3 [deprecated = true];
  string display_name = 4;
  reserved 5, 6; // Reserved for future use
}

Common Mistakes

1. Changing field numbers — Breaks binary compatibility.
2. Removing fields — Use reserved keyword.
3. No package version — All services in one namespace.

Practice Questions

1. What is the most important rule in Protocol Buffers compatibility?
2. How do you deprecate a field in protobuf?
3. What is the purpose of the reserved keyword?

Challenge

Take an existing protobuf definition and evolve it by adding two fields, deprecating one, and reserving one. Ensure backward compatibility.

What's Next

In the final lesson, you will complete a versioning project.