Azure DocumentDB was released for general availability on April 8, 2015. Since then, we have released several version updates, each refining the protocol and adding new features. The latest SDKs offer the best performance and most comprehensive set of capabilities for DocumentDB developers. Prior to the release in April we ran a limited support public preview of the service that had its own service version and associated client SDKs.

Today we are announcing the upcoming retirement of preview versions of our REST API and client SDKs. This post outlines all you need to know to ensure that your application continues to run well after these versions have been removed.

Background: DocumentDB versioning

Azure DocumentDB is accessed using the service REST API. This API was first released in August 2014 when the service was released to preview. As we have improved the service through numerous additions and changes, we have used versioning to maintain compatibility with existing applications. Any time we make a change that could break an existing application, we introduce a new version, which applications must explicitly opt-in to use. Existing applications are unaffected by the new version’s existence. Calls to DocumentDB can explicitly specify the version to be used by setting the x-ms-version HTTP header in the REST request. If this header is not set, the most recent version is used to serve the request.

What about client libraries, SDKs and tools?

The majority of our users consume DocumentDB through the use of published client libraries provided by Microsoft. Each of these client libraries wrap calls to the REST API and are bound to a specific version of this API.

What’s changing?

Our approach to versioning is unchanged – we will continue to introduce new versions of our REST API whenever we make changes that are incompatible with an existing version. However, we are now retiring previous versions of the REST API, and the associated preview client SDKs.

Retirement details

What versions are being retired?

All versions prior to version 2015-04-08 will be retired on February 29, 2016. This includes the following versions:

• Version 2014-08-21 (released prior to general availability)

The following versions are unaffected and continue to be fully supported:

• Version 2015-04-08
• Version 2015-06-03
• Version 2015-08-06 (current version)

For more information on the REST API and which versions are currently supported, please refer to Azure DocumentDB API Reference documentation on MSDN.

When will these versions be removed?

The affected versions will be removed on February 29, 2016.

What will happen when these versions are removed?

Requests which are explicitly versioned using x-ms-version request header (set to one of the removed versions) will fail, receiving an HTTP 400 (Bad Request) status code.

Minimum supported versions, libraries, SDK’s

Users should upgrade to the latest version of the client SDK whenever possible.

Any client SDK released prior to general availability, on April 8, 2015, where the version number is less than 1.0.0 (0.9.x-preview) will be retired and not supported beyond February 29, 2016.

The below table is provided to allow users to quickly see if they are using any components that target versions which are to be retired.

Language	Earliest supported version	Current version
.NET	1.0.0	1.5.0
Node.js	1.0.0	1.5.0
Java	1.0.0	1.5.0
Python	1.0.0	1.5.0

What should I do?

It is recommended that users begin their application upgrades, to at least the earliest supported version for their appropriate platform as early as possible to avoid being impacted when the preview service versions are removed on March 1, 2016. To review the version differences for each of the SDKs and identify APIs that have been changed, see the release notes for .NET, Node.js, Java and Python.

If, for whatever reason, you are unable to upgrade your applications in the months leading up to March 1, 2016 please contact the Azure DocumentDB team prior to the cut-off date for assistance.

Conclusion

If you are new to DocumentDB, try it out today by signing up for a free trial and create a DocumentDB account.

If you need any help or have questions, please reach out to us through the developer forums on MSDN or Stack Overflow.

Stay up-to-date on the latest DocumentDB news and features by following us on Twitter @DocumentDB.