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: v1beta1, v1beta2, v2beta1, and so forth.
Stable APIs keep it simple: v1, v2, and so on.
Any changes introduced within a major non-beta version are guaranteed to be backward compatible.
Keeping our Backwards Compatibility Promise
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.
Backwards-compatible changes
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!).