This document describes how we apply versioning to the DataSift REST API and how we support and deprecate legacy versions to give you time to transition to the latest version.
The DataSift API is versioned so that we can communicate changes to the platform and give you information to keep your applications running.
API version numbers are in the format major.minor. The current API version is v1.3.
The major version number will rarely change as we reserve this for major changes, such as a complete redesign of the API.
The minor version number is incremented each time we introduce a 'breaking change'.
What is a breaking change?
A breaking change is an update that may require you to make changes to your application to keep using the endpoints.
For example if we changed the structure of the data returned by an endpoint, you would need to change your code to parse the new structure. So for such a breaking change we would up the minor version number, whilst continuing to support the API version you are currently using, allowing you time to move to the new API version and amend your code.
When we add additional endpoints or optional parameters to endpoints we do not update the version number because these simply add additional functionality, but no breaking change.
How do I know which version I'm using?
When you call the API the URL you use indicates the version you are calling. For example the following URL indicates usage of version 1.1 of the API:
curl -X GET https://api.datasift.com/v1.1/usage?period=day -H 'Authorization: datasift-user:your-datasift-api-key'
If you are a long term customer of DataSift you may have called the API without a version number in the URL - in this case you are using version 1.0 of the API.
Regardless of the URL you use you can also see which version of the API you have called by looking at the X-API-Version header in the response. For example the above CURL example would return:
What if I'm using a DataSift client library?
When you download a client library it will be set up to use the latest production version of the API.
The easiest way to stay up-to-date with the API is to upgrade to the latest client library version when it is released.
You can subscribe to the announcements category on the community site to keep track of client library releases. Here we post details of new releases and detail the API version they support.
Where can I find documentation on the changes?
Each API endpoint has a dedicated page within our documentation. Each of these pages contains details on how the endpoint has changed with each version of the API if changes have been made.
For example the page for the push/create endpoint states that in version 1.2 of the API, support for the playback_id parameter (a synonym of historics_id) was dropped:
We support all versions of the API for at least 12 months after they are released. We recommend you move to the latest version as soon as you can after a release.
We will give customers 3 months notice of when we deprecate a version of the API.
You can subscribe to the announcements category on the community site to keep track of API changes. Here we post details of new releases and will warn you of deprecation of API versions in advance.