Cumulocity is committed to an extremely high degree of backwards API compatibility between releases. Devices and applications interfacing with Cumulocity will work for years unmodified even though Cumulocity is constantly being developed and upgraded. We ensure this with thousands of automated tests that run against every version of Cumulocity. This short article provides some guidelines to benefit from this API compatibility.
The general guidelines are:
API compatibility. Cumulocity's published REST, SmartREST and MQTT APIs are guaranteed backwards compatible. We may introduce new REST resources, new methods, new properties, new query parameters and so on, but we will not change the behaviour of an existing API. If you use an API, you can be sure that it will work also after Cumulocity has been upgraded.
Beta APIs. In general, we strive to publish all APIs. We may hold back some APIs in a beta state to make sure that they are robust enough so that we can keep our promise. Please keep this in mind if you start using APIs that are not documented on our web site, but already visible, for example, if you peek into our web applications using the developers tools of your browser.
SDK and client library compatibility. On top of the REST and MQTT APIs, Cumulocity includes SDKs and client libraries. For the programming APIs inside the SDKs and the client libraries, we do not guarantee full backwards compatibility. However, when you develop software, you can stay with a particular version of the SDKs or client libraries for as long as you wish. If you decide to upgrade the version of SDK or client library that you use, you should retest your development. You may need to perform some changes to make use of the new version. We certainly do not want to cause you additional work, but in some cases, this is simply unavoidable due to the rapid development that our SDKs have.
No forward compatibility. We guarantee backward compatibility, not forward compatibility. You can check this using the version of the SDK and the version of the platform. If you wish to develop a device or application against, say, Cumulocity 9.0, please make sure that the client library or SDK that you use has version 9.0 or lower. If you take the latest SDK version, build an application with it and deploy on an older Cumulocity version, this is not guaranteed to work. The SDK may make use of APIs that are simply not yet present in the older version.
Applications and microservices. For clarification, the same versioning policy applies to applications and microservices provided directly by Cumulocity. You can, in general, run an older application or microservice version against a newer Cumulocity backend. This is required to be able to upgrade Cumulocity in an online fashion.
Version schema. For clarification, Cumulocity uses a three digit versioning scheme. For compatibility checks, only the first two digits are usually relevant. The third digit counts maintenance builds without functional changes or API changes.
We hope that these guidelines help you in developing very robust and long running software on top of Cumulocity.