The Clumio REST API is designed to be versioned by resource rather than at the API level.
Each resource may support multiple versions, and each version supports a list of operations. For example, the users resource may include one set of operation IDs in major version 1, and another set of operation IDs in major version 2.
Each resource can be versioned independently.
When backwards-incompatible changes to a resource occur, a new version of that resource will be released. Clients who continue to use the old version are protected from backwards incompatible changes. Examples of backward incompatible changes include:
- Renaming a response field.
- Removing a response field.
- Adding a required request parameter.
- Renaming a request parameter.
- Changing the order of the items in an array response.
Changes which are guaranteed to be backward compatible will not introduce a new version. Examples of backward compatible changes include:
- Adding an optional request parameter.
- Adding new fields to a response.
- To see a list of resources and their supported versions, run the Discovery endpoint (
GET /).
Every request must include an HTTP header with the Accept key to define the version of the API to be used. The value of the Accept header should be specified in the following format, where <version> represents the version to be used.
Accept: application/api.clumio.*=v<version>+json
In the following example, the request header uses *=v1, meaning all resources use v1:
Accept: application/api.clumio.\*=v1+json
To determine the newest version for each resource, run the Discovery endpoint GET /. The newest version string is sent in the response header and looks similar to the following example:
Content-Type: application/api.clumio.\*=v1+json
See Discovery API for more information.
The version string can be customized to specify different versions for different resources using the following ampersand-separated format.
Accept: application/api.clumio.\*=v2&users=v3&tasks=v1+json
For example, when a request is submitted with the above version string, every resource will use v2 except for users and tasks, which will use v3 and v1 respectively.
Note that since each resource can be versioned independently, the same URL may provide different request/response formats based on the resource version specified.
To upgrade to a newer REST API version, change the version string.
Important! Before you upgrade to a major version, test your code against the target version by modifying your version string, and adjust your script accordingly. For more information about Clumio releases, refer to the Clumio Release Notes.
Version Deprecation
The Clumio REST API will remove support for old versions according to the following policy:
Six months after the release of a new version, support for the old version will be removed.
Depending on the adoption rate of the endpoint, if the impact of a change is deemed to be minimal to clients, old versions may have their support discontinued more quickly, but the old version will always persist for at least one month after the release of the new version.
The introduction of new versions and the removal of support for old versions will be published in the Changelog section.