Versioning

CCP has its own api versioning scheme on top of the versioning of the OData protocol. The OData versioning indicates the OData standardized protocol version. The CCP one indicates the version of the CCP api. CCP versions are very helpful because changes to the api, even major ones, don't impact client applications which haven't been updated to the newest version. When an application is built on a specific version of the api, these application keep working as long as that api version is supported by CCP.

To use api versioning one needs to add a set of http headers to the request named CabmanCloudPlatformVersion and MaxCabmanCloudPlatformVersion. The first header is used to tell the platform which version of the request the application uses. The response will be in the same version if that version is still available. When it's not available and the header also has a MaxCabmanCloudPlatformVersion header, this version is used. If the request changed between the two versions and does not conform to the maximum version an error will be thrown.

Rules

• Versions conform to the major.minor scheme (e.g “11.0”)
• If none of the versioning headers are included the latest version is implied.
• If the version in both CabmanCloudPlatformVersion and MaxCabmanCloudPlatformVersion is not available (invalid or removed) an error will be thrown.
• If CabmanCloudPlatformVersion is included and MaxCabmanCloudPlatformVersion is not included, the latest version is implied.
• Even though the OData standard says that additions (e.g new functions, entities, properties) must be supported by every client while maintaining the same version number, CCP does increase the version number for the API even when there are only additions. It is still required that a client does not break with additions but api level is increased for convenience and api clarity.