Backward Compatibility
Backwards compatibility considers:
-
Source compatibility
Code written against a previous version of an SDK, Library, or Protobuf definition must compile and run successfully against a newer version. -
Wire compatibility
Code written against a previous version must be able to communicate correctly with a newer server.
This covers compatibility of inputs and outputs, serialization/deserialization format, protocol and authentication behavior. -
Semantic compatibility
Behavior of newer versions must be compatible with what operators, and existing software, expected when using previous versions.
Protobuf and gRPC
The Protobuf definition language, and the gRPC protocol, are designed to allow evolving APIs and data models while maintaining backward compatibility.
This reduces the need to release new major versions, implement a transition strategy, and handle the complexities of supporting multiple active versions.
Wire and source compatible changes
-
Adding new fields to existing data models, requests and responses
Older clients will ignore newer fields without causing errors. -
Adding new Enum values
Older clients will treat unknown enum values as their default (zero) value. -
Adding new data models (Protobuf messages)
Older clients will ignore newer data models -
Annotating fields as deprecated
Allows to notify developers about planned removals, without creating breaking changes. -
Adding new RPC methods
Older clients will ignore methods they do not call.
Source Incompatible changes
Wire compatible but Source Incompatible changes:
- Renaming enum values
- Renaming a field
- Renaming data-model or package name
- Removing a field or enum value, and marking its tag number as reserved
(Older clients can still send data through the removed field, but it will be ignored by newer servers)
Wire Incompatible changes
Breaking changes in both wire and source compatibility:
- Changing the type of a field
- Changing tag numbers
- Changing members in oneOf grouping