Versioning

Introduction

Because over time, data types and request signatures may change due to added functionality, a new method is being introduced to control which version of a particular resource is requested by the client.

This allows clients to gradually upgrade to new features in their own time, while allowing the service to be upgraded in the background.

Specifying which version to request is done by adding a parameter to the "Accept" and "Content-Type" header.

Example

This example applies to an old version of the WebTSM Services (3.8.x), but applies to future changes within all 3.9.x releases just the same.

Calling an instance of the service with version 3.8.1 with

CODE

GET /repositories/{repository}/timeseries/{ID|name}/data

and

CODE

Accept: application/json

would return a list of objects containing time series data with only the from-timestamp.

This may cause issues with clients that are used to getting the data with a from- and a to-timestamp, which is what the service returned under this resource prior to version 3.8.1.

Clients can force a particular version to be retrieved by adding a "api-version" parameter to the media type:

CODE

Accept: application/json;api-version=3.8.0

This would return the same objects with two timestamps as version 3.8.0 would have.

A media type without api-version parameter simply returns the latest version of a particular request by default.

The same concept applies to the "Content-Type" header.

Media Type parameters can be combined of course, so adding indentation & versioning would look like this:

CODE

Accept: application/json;api-version=3.8.0;indented=true

Lifetime of API Versions

Versions of specific requests remain available only within one "minor" release.

Example

Assuming you're accessing a service version 3.8.2, and the format of the response to a request has changed since 3.9.1 you may specify

CODE

api-version=3.8.0

or

CODE

api-version=3.8.1

or

CODE

api-version=3.8.2

in your request headers to specify which format you would like to receive from the service.

Once a new "minor" version is released, this service only retains the most recent format for any request. Calling the service with an api-version parameter smaller than that will result in an error (406 Not Acceptable)

So in the above example, assuming 3.8.2 is followed by a 3.9.0 release, when accessing a Service with version 3.9.0, passing any one of the aforementioned values for api-version will result in a failure. Making the request with

CODE

api-version=3.9.0

or without an api-version parameter will return the data the same way as it did when specifying

CODE

api-version=3.8.2

or no api-version parameter at all.

This of course assumes that there is no format change between versions 3.8.2 and 3.9.0, in which case, the most recent format would be returned instead.