<<

API versions

New API versions will be released from time to time. API version number contains of 3 integers separated by dots, for example 2.0.0. API version is contained in the URL you POST the JSON request to or in the SOAP endpoint URL, for example https://api.cloudmonit.pl/2.0.0/json_api or https://api.cloudmonit.pl/2.0.0/soap_api

If you want to stick to a particular version, make sure that you send your request to the correct URL.

API responses contain a version field - it contains the API version number.

Interface changes

When the last part of the version number changes (for example from 2.0.0 to 2.0.1), the API interface does not change. Examples include bugfix releases and optimizations. It means that you can seamlessly switch to the new version and everything will work as before.

The change of the second number (from 2.0.0 to 2.1.0) may contain interface modifications and therefore your applications may require adjustments if you want to make use of it. All interface incompatibilities will be listed in the new version's release notes.

Finally, the change of the first number means very big changes to the API, that modify the interface significantly.

Version aliases

Instead of using a particular version, you may like to use a version alias, such as stable or beta. That way you will always use the current API version. Available API aliases include:

• stable

  The latest stable API version.

• beta

  The latest testing API version.

• X.Y.stable

  The latest stable version from a branch (for example 2.0.stable will be the latest stable version from the 2.0 branch). It guarantees the newest version while still being safe from the interface changes (as described above).

Checking version

You can specify the API version (or its alias) you would like to use in your request by passing it in the version request attributte. The API will return an error if the version does not match the requested version.

This mechanism can be used to implement a client that automatically uses the new API versions while still caching the WSDL or JSON module specifications. For example, you send the requests to 2.0.0, always checking that it is the "stable" version. When the stable version changes you get an API version error - you drop the WSDL cache and switch to the new version.

<<