All Mnemonic APIs (Protobuf and REST) are strictly versioned. All packages and endpoints have corresponding version tags.

We follow common idioms for versioning APIs:

  • Beta version v#beta# for packages that are still in development and MAY have breaking changes.
  • Major versions v# for packages that are stable and must not include backward incompatible changes.

In development APIs are always versioned as: v1beta1, v1beta2, v2beta1 etc.

Stable APIs are always versioned as: v1, v2 etc.

Examples of packages and corresponding API paths in REST:

  • package;/events/v1beta1/transfers/...
  • package;/events/v1/transfers/...

Any changes introduced withing a major non-beta version are guaranteed to be backward compatible.

Maintaining backwards compatibility

One of the core promises of our Protobuf and REST APIs is to never introduce breaking changes. We strictly maintain and enforce our APIs with breaking change detectors and linters to prevent this from ever happening.

Backwards-compatible changes

Mnemonic considers the following changes to be backwards-compatible:

  • Adding new API endpoints, services, methods.
  • Adding new optional request parameters.
  • Adding new properties to the existing API responses.
  • Changing the order of properties in existing API responses (but not fields enumeration!).