Interface Versioning

The MyDataHelps interfaces are continually evolving and adding new capabilities. This article describes the versioning strategy.

Tip
For a list of API and SDK updates, see Release Notes.

Versions

The REST API uses a singular, increasing version number (v1, v2, etc.). A change in version indicates a major change in functionality that is not backwards-compatible. Backwards-compatible updates will occur transparently, without a change in version number.

The SDKs use semantic versioning (Major.Minor.Patch, e.g., 1.0.2) where:

Major Version - Reflects major changes in functionality that are not necessarily backwards-compatible.
Minor Version - Reflects when new, backwards-compatible features are added.
Patch Version - Reflects backwards-compatible bug fixes or other trivial updates.

Selecting a Version

For the REST API, the version is part of the resource URL. For example: /api/v1/administration/projects/:projectId/participants.

For the SDKs, you select a version when you include it in your application. For example:

JS SDK version x.y.z: <script src="https://cdn.careevolution.com/mydatahelps-js/x.y.z/MyDataHelps.js"
iOS SDK version x.y.z: .package(url: "https://github.com/CareEvolution/MyDataHelpsKit-iOS", from: "x.y.z")

Backwards Compatibility

Changes which are additive are generally considered backwards-compatible. These include (but are not limited to):

Adding a new REST API resource.
Adding a new request type (e.g., POST) to an existing REST API resource.
Adding a new response field to an existing REST API request.
Adding a new optional body/query parameter to an existing REST API request.
Adding a new SDK method.
Adding a new, optional parameter to an existing SDK method.
Adding a new field to an SDK class/object.

Deprecation of Old Versions

Older versions of the SDKs and REST API will continue to be supported for at least six months after a new version is released, allowing customers to upgrade at their own pace.