Skip to main content
Version: 1.1beta2

Versioning and compatibility

A released version in Clarify has the syntax MAJOR.MINOR.PATCH. For each MAJOR.MINOR combination, only the latest PATCH release is selectable, using a selector string of "MAJOR.MINOR".

A pre-release version in Clarify has the syntax MAJOR.MINOR.PATCH-IDENTIFIER. Where the identifier is either of syntax beta.N or beta.N.M. In practice, pre-releases only makes sense to do when incrementing either the MINOR or the MAJOR number, hence the typical version selector string will be "MAJOR.MINORbetaN".

The versions selection string is supplied as an HTTP header.

1.01.0.3MAJORMINORPATCH1.1beta21.1.0-beta.2.1MAJORMINORPATCHPRE-RELEASE IDENTIFIERVersion selectorFull version
A version selector string maps to the latest PATCH or beta.N.M release.

Semantic versioning

For documentation purposes, the full version string of the Clarify API is following the rules of Semantic Versioning, which means that we use the version number to document backward compatibility:

  • An increment of the MAJOR version indicates breaking changes to the API.
  • An increment of the MINOR version indicates new backwards-compatible features.
  • An increment of the PATCH version indicates noticeable bug fixes or backwards compatible changes to limits, field validation, etc.

Because we are writing a JSON API that needs to work with multiple programming languages, we define backward compatibility in a particular way which you can read more about in our "Backward compatibility promise" below.

Backward compatibility promise

Use explicit version selection to mitigate risks

While we recommend all code to use explicit version selection, it is particularly important for code that rely on positional RPC parameters, or have JSON parser implementations that are sensitive to the presence of unknown fields.

This promise is to be viewed as a promise of intent, and not a legally binding agreement. Still, we will do what we can to uphold this promise to the best of our ability.

All versions 1.X.Y should retain backwards compatible with all previous versions 1.X.Y, except for the cases listed below:

  • If a feature is completely removed from Clarify, we may be forced to remove functionality in all MAJOR.MINOR versions of the API. The threshold for doing this should be considered high, but if it happens, we will explicitly allow for breaking changes to occur in both MINOR and PATCH releases as a means of documenting feature removal.
  • If a serious security concern require that we introduce breaking changes to the API, we will explicitly allow it to occur in both MINOR and PATCH releases.

We define the following changes to be backwards compatible:

  • Add new optional parameters to existing methods.
  • Change the order of existing JSON RPC method parameters.
  • Change the order of properties/fields in any JSON object in the response.
  • Add new properties/fields to any JSON object in the response.
  • Add new error codes.

To aid any clients that are sensitive to the issues above, we will avoid doing the following changes as part of a PATCH release:

  • Change the order of existing JSON RPC method parameters.
  • Add new properties/fields to any JSON object in the response result.

Using pre-releases

Use at your own risk

Pre-releases can be potentially unstable, and will eventually be removed. All usage happens at your own risk, and we offer no guarantees for how long the pre-release will remain available, or that breaking changes won't occur for any given version selection string.

In Clarify, the format of a pre-release identifier suffix is either -beta.N or -beta.N.M. Here we use the N.M numbers to indicate intended backward compatibility:

  • An increment of the N number indicates breaking changes to the API.
  • An increment of the M number indicates new features that are intended but not guaranteed to be backwards-compatible.

Breaking changes should also be expected between a pre-release and the final MAJOR.MINOR.PATCH release.

Bug fixes for pre-releases may be done without any additional ceremony or documentation effort. A feature is considered added when it first gets documented, and not when it's first made available in the pre-release API.