Backward compatibility keeps newer software working with existing users, integrations, or client code. Design public interfaces so improvements do not unnecessarily break consumers. section 4.1.1 section 10.1.1
Apply compatibility-conscious design by:
- Keeping Protobuf field numbers permanently associated with their fields, so later versions can still recognize existing data. section 10.1.1
- Defining dedicated request and response messages for gRPC endpoints, even when they are empty or contain one field. section 10.1.1
- Changing private or unexported implementation details more freely while keeping exported functions, types, variables, and constants stable. section 4.1.1
Evolving a habit service
A Habit message assigns name the number 1 and weekly_frequency the number 2. Future versions can add fields without reassigning those identifiers. A CreateHabit endpoint uses CreateHabitRequest and CreateHabitResponse rather than passing Habit directly, leaving room for smaller interface changes. section 10.1.1
Listing 10.3 habit.proto: Defining the Habit message
// Habit represents an objective one wants to complete
// a given number of times per week.
message Habit { #1
// Name of the habit, cannot be empty
string name = 1; #2
// Frequency, expressed in times per week.
int32 weekly_frequency = 2;
}
Inspect the Habit message to see stable numeric field identifiers in a concrete Protobuf declaration. section 10.1.1
Listing 10.6 service.proto: Request and response
import "habit.proto"; #1
service Habits {
...
}
// CreateHabitRequest is the message sent to create a habit.
message CreateHabitRequest {
// Name of the new habit. Cannot be empty.
string name = 1;
// Frequency of the new habit. Will default to once per week.
optional int32 weekly_frequency = 2; #2
}
// CreateHabitResponse is the response of the create endpoint.
message CreateHabitResponse {
Habit habit = 1;
}
Inspect dedicated request and response messages that allow a gRPC endpoint to evolve without unnecessarily breaking its API. section 10.1.1
