Operation Versioning

Cherwell REST API operation versioning is possible with these operations:

  1. Add the operation version in the URL. (Example: http://localhost/CherwellRESTAPI/api/v1/serviceinfo)
  2. Add the operation version in a custom header attribute. add x-api-version header to the request specifying the operation version number. (Example: http://localhost/CherwellRESTAPI/api/serviceinfo with a header x-api-version: 1)
  3. Add a value to the Accept header. (Example: http://localhost/CherwellRESTAPI/api/serviceinfo with the Accept header application/json ; api-version=1)
  4. Add a query string parameter to the URL. (Example: http://localhost/CherwellRESTAPI/api/serviceinfo?v=1)

The operation version of the Cherwell REST API differs from the underlying CSM version, though an installation is dependent on a version of CSM.

Operations will increment versions when request/response contracts are changed by removing properties, changing property data types, or changing the schema of complex data types of properties.

An operation version of an operation remains the same as long as there are no breaking changes to the request/response contracts.

The operation version will not be incremented for each CSM release unless breaking changes were made. New operations will be added as version 1 of those operations. If no version is specified, v1 is used. If a version is in the URL and that does not exist, the operation will not be found. If the version is in the URL, it will override all the other version specifying operations. For example, if operation 2, 3, or 4 are used, the URL cannot have a version segment.