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!).