Legacy API Version Control

The content found on this page applies only to the Legacy API. As of 01/01/2019, developers have only been issued credentials to our new Inform Platform. If you're a new Validic customer, please review the Inform API Documentation. Content found on this page is for informational purposes only. We have no further product releases scheduled for version one of our API (v1.2016-03-01). All new product features and integrations will be exclusive to our Inform API. At this time, we continue to support v1.2016-03-01 and provide the support you have come to expect from Validic. However, you REALLY should consider moving to our new platform as your development schedule allows. With the release of Inform, we have introduced several new features to help improve the Validic experience, such as:

Near real-time API
New data sources like continued glucose monitoring and intraday step data
Improved data model and implementation which reduces operational costs

How to prepare for change and manage your version.

In order to enhance the Validic API without impacting existing customer implementations, Validic maintains multiple versions of the API. This system allows the customer to manage which version they are using and change at their own pace. Versions are managed in the API request and response headers.

Any changes made to the API that are deemed backward-incompatible will be made in a new minor version, designated by the approximate date of that update. You can verify the version used in your request by reviewing "Validic-Version" in the response header.

You can always review previous versions and changes in our Change Log.

Backwards-compatible (Non-Breaking) Changes

The following list of changes is considered compatible with existing integrations and will not require an updated version of our API as they should not disrupt your current integration. Your system should be configured to accept, or ignore, these types of changes as they arise:

Adding a new resource (e.g. a new data object)
Adding a new optional request parameter to an existing method
Adding new property to a response
Changing the order of properties in an existing response

Below is an example of a backwards-compatible change:
Adding new properties and changing the order of properties in Apps.Json:

Before

{
          "name": "Withings Pulse Activity Tracker",
          "type": "Wearable",
          "description": "An 8-gram smart tracker to monitor your activity 24/7, measure your heart rate and improve your health. The Withings Pulse can help us all be more active. It captures steps, burned calories, elevation climbed and distance traveled. ",
          "excerpt": "8-gram smart tracker to monitor your activity.",
          "resource_url": "http://www.withings.com/en/pulse",
          "data_objects": [
            "fitness",
            "sleep",
            "biometrics"
          ],
          "kind": [
            "Routine",
            "Sleep",
            "Biometrics"
          ],
          "image_url": "https://s3.amazonaws.com/assets.validic.com/assets/Withings_Pulse_Activity_Tracker.png",
          "discontinued": false
        },

After

{
          "data_objects": [
            "fitness",
            "sleep",
            "biometrics"
          ],
          "description": "An 8-gram smart tracker to monitor your activity 24/7, measure your heart rate and improve your health. The Withings Pulse can help us all be more active. It captures steps, burned calories, elevation climbed and distance traveled. ",
          "discontinued": false,
          "excerpt": "8-gram smart tracker to monitor your activity.",
          "image_url": "https://s3.amazonaws.com/assets.validic.com/assets/Withings_Pulse_Activity_Tracker.png",
          "kind": [
            "Routine",
            "Sleep",
            "Biometrics"
          ],
          "name": "Withings Pulse Activity Tracker",
          "resource_url": "http://www.withings.com/en/pulse",
          "supported_activity_types": [],
          "type": "Wearable"
        },

Backwards-incompatible Changes (Breaking Changes)

The following list of changes are considered breaking changes and will only be released in a new version of our API. Your system will not be required to immediately change to the new version, however, you should anticipate that we will eventually deprecate or eliminate support for older versions.

Renaming a property in a response
Adding a new required request parameters to an existing method
Changes to HTTP status code responses
A new error condition in response to a request parameter value
Any change which disrupts the reasonable and expected use of REST API's

Versions

Validic uses a major/minor versioning system to manage changes to our API. These versions will allow a user to control which version they access and prevent disruptions to their service. The following sections will review major and minor versions and explain how they will impact you.

Major Version

The major version represents our API as a whole. Think of this as the entire product. This version is not impacted by product improvements and corrections. The major version will only change if a new interpretation of our API is released. Our current major version is V1. This is visible in the API request URI. For example:

V1

GET https://api.validic.com/v1/organizations/5400864SAMPLEd683000004/fitness/latest.json?access_token=9ff1217aSAMPLE689a3e2fce700de973879SAMPLEddc871604a277cb901b2&start_date=2015-10-01T08:44:29Z&end_date=2015-12-03T08:54:27Z&limit=200

Updates to major versions are uncommon and should not impact day-to-day operations.

Minor Version

The minor version indicates which version of the API you're using to access Validic. The version is represented by the date the version was released, such as "2016-01-01". Developers can control their version by adding "Validic-Version: " to their header.

HTTP

Version Control

When you first create your Validic organization, Validic assigns your organization to the current version of our API. Thus, if you do not provide a version in the request header, your requests will use your assigned, or default, version number. This default version number will stay the same until that API version is deprecated. If your default API version is deprecated your default version will be moved to the next closest API version. For instance, if API Version '2015-01-01' is deprecated and the next closest version is '2015-04-01', we would move you to this version - and not to the most current version. By adjusting your default version as little as possible, we dramatically decrease the chances of disrupting your service. Please read more about this process and the deprecating of API versions in the API Deprecation section.

👍
Creating New Organizations
When creating a new organization, please review the version in your header to ensure it matches your existing integrations. New organizations are pinned to the current version when they are created.

Depreciation and Release Schedule

Typically Validic will release 4 per year, however, additional releases may occur from time to time. Once a new minor version is released, the previous version will be supported for one year. After one year, the release will remain active, yet unsupported for one year. Two years after release the version will be deprecated and any users still utilizing this version will be moved to the next available version.

For instance:

An organization is assigned a default Validic-Version = '2016-01-01'
Validic-Version: 2016-04-01 is released. A notification is sent to all users currently using Validic-Version: '2016-01-01' notifying them that a new version is available and that their current version will be supported until 2017-04-01.
On 2017-04-01 notification is sent to all users of Validic-Version: '2016-01-01' notifying them their version is no longer supported however will remain active, albeit unsupported, until 2017-04-01.
On 2017-04-01, version Validic-Version: '2016-01-01' is fully deprecated. Any users still using this version are automatically moved to the version closest to their deprecated version. In this case, they'd be moved to Validic-Version: '2016-04-01'.
This process will continue as each version is deprecated.

Supported vs Unsupported

When planning your update schedule, it is essential to understand the difference between supported and unsupported versions. While a version is supported, it will continue to receives backward compatible updates and full technical support. Once a version is unsupported, while it can still be accessed, it will no longer receive any updates, including bug fixes, and technical support may not be provided. It is therefore possible, albeit unlikely, that an unsupported version of the API will stop working based on updates made to the Validic system. Additionally, if you wish to take advantage of new features, fixes, and updates, you must upgrade to a newer version of the API.

If you have any questions regarding versioning, please contact our support@validic.com.