At Mnemonic, we're adamant about clear API versioning for our Protobuf and REST interfaces. All packages and endpoints come with their specific version tags.
Let's break down how we handle versioning:
- Development stage packages use a
v#beta#format. They're still in the pipeline, which means there might be breaking changes down the road.
- Stable packages use a
v#format. They're rock solid and guaranteed to steer clear of any backward incompatible modifications.
Beta APIs are labeled like so:
v2beta1, and so forth.
Stable APIs keep it simple:
v2, and so on.
Any changes introduced within a major non-beta version are guaranteed to be backward compatible.
Both our Protobuf and REST APIs come with a no-breakage guarantee. We're vigilant about avoiding breaking changes and deploy tools like breaking change detectors and linters to make sure we stay on the straight and narrow.
Here's what Mnemonic considers to be backward-compatible changes:
- Introducing new API endpoints, services, or methods.
- Adding optional request parameters.
- Expanding existing API responses with new properties.
- Shuffling the order of properties in existing API responses (but we never mess with field enumeration!).