Learnosity Simplified Versioning

Since the 6th of June 2018, the following versioning pattern is in use.

Instead of calling each API’s specific version, you call a single version, and we manage the complexity of serving up the correct version.

For example, rather than calling Items API v1.81 & Author API v1.31 and Reports API v1.4 – you simply specify 2018.1.LTS for all of them, and know the versions will all work together in perfect harmony.

For example:

For further information and frequently asked questions you can read our Easier Versioning for Learnosity APIs Blog Article.

Learnosity API versioning (legacy)

The Learnosity APIs will be available from: https://<api_name>.learnosity.com/, which will provide the latest available version of the API.

The different API releases/versions will be available following the pattern https://<api_name>.learnosity.com/?vX.Y.Z , with each version number being in compliance with SemVer. This means that version 1.0.3 of the API will be available at https://<api_name>.learnosity.com/?v1.0.3

In order to simplify usage/inclusion of the API, there will also be API URLs that will provide access to the latest stable release within a major or minor version. This means that if the latest version available within v1.2 is v1.2.13, accessing https://<api_name>.learnosity.com/?v1.2 will give access to that one.

The following table summarises the available options:

For production environment we recommend using URLs at minor version level, to ensure optimum stability with bug fix coverage. Use of a fully specified release version is discouraged for production but is available for regression testing, etc.

Summary of release versioning implications

Given a version number X.Y.Z,

• a change of X implies that new, backward incompatible functionality has been introduced to the API.
• a change of Y implies that new, backward compatible functionality has been introduced to the API.
• a change of Z implies only bug fixes to incorrect behaviour without adding or changing existing functionality.

Background on SemVer

The versioning approach is based on Semantic Versioning (SemVer). Its main points are:

• A version number must take the form of X.Y.Z where X, Y and Z are integers. 
  X is the major version, Y is the minor version and Z is a patch version. 
  In the case of special versions, this may be denoted by appending an arbitrary string immediately following the patch version, e.g. 1.0.9beta1 .
• Major version zero ( 0.Y.Z ) is for initial development. Version ( 1.0.0 ) defines the first stable release of the public API.
• Version numbers must be incremented after introducing changes to the public API, the rules for incrementing are dependant on the type of change as follows:
  • If a backwards compatible bug fix is introduced to the public API, the patch version Z ( x.y.Z ) MUST be incremented. 
    A bug fix being an internal change that fixes incorrect behaviour.
  • If a new, backwards compatible functionality is introduced to the public API, the minor version Y ( x.Y.z ) MUST be incremented. 
    It MAY be incremented if substantial new functionality or improvements are introduced within the private code.
  • If any backwards incompatible change is introduced to the public API, the major version X ( X.y.z ) MUST be incremented.

The versioning approach should be reflected in the version control system by the use of tags following the same naming pattern. Tag that represent releases in the version control system MUST be vX.Y.Z, e.g. "v1.2.6". The first revision that introduces SemVer compliance should be tagged "semver" to signal the point after which compliance with SemVer should be expected/enforced.