Chapter 27: API Versioning Strategies
Package-Based Versioning (Recommended)
// v1 — stable
package mycompany.users.v1;
service UserService { ... }
// v2 — breaking changes
package mycompany.users.v2;
service UserService { ... } // different package = different service
When to Create v2
- Removing a field that clients depend on
- Changing field semantics (same name, different meaning)
- Restructuring message hierarchy
- Changing RPC semantics
When NOT to Create v2
- Adding new fields (backward compatible)
- Adding new RPCs (backward compatible)
- Adding new enum values (backward compatible)