API Backwards Compatibility

Backwards Compatibility Overview

The VOSS-4-UC API is versioned and while the latest API and models are in use, the system is backwards compatible with earlier API versions for several models and operations on these. This means that API requests follow the schema and data as specified by the API version.

Note

Please note that from release 19.1.1 onwards, if the VOSS-4-UC installation is a new installation, in other words not upgraded, then the system will not automatically have backwards compatibility support for older API versions.

For such systems, if support for older API versions is required, then the systems will require the separate subsequent installation of version specific backward compatibility files (VSF bundles). Contact your VOSS representative for information on the required VSF bundles.

From 10.6.2 onward, the default web server security protocol has been set to TLSv1.2, and the TSLv1 and SSLv3 protocols are no longer supported.

It is therefore easier to use a network device or custom code written for an earlier VOSS-4-UC version. An HTTP Request parameter or Header change in developer code may be required for API calls.

Third-party clients that are written to use a particular API version continues to work against newer servers as long as the VOSS-4-UC server continues to support the API version used by the client. VOSS-4-UC supports APIs from the current release and two previous releases (N-2).

For device models, an internal version mapping table for API versions and device versions is also maintained. This table creates a fixed mapping of device versions to API version. The mapping is created on a principle of the latest supported device version at the time of the API version release. For example, the version 10.0 UC Application schema is mapped to API version 10.1.2.

No transforms are carried out on Relation models, because transforms are carried out on their component Data- and Device models.

Tools such as Bulk Load and Search, are backwards compatible from an operations and URL structure point of view. However, the data processed or generated by the tools do not support Backwards Compatibility. Data must be adapted to conform to the latest schema when presenting it to the API. Data obtained from the Tool interfaces are interpreted according to the latest schema.

Note

For Update operations: if a model schema was changed so that a new field is added to a schema within a list of objects and data exists in the field for a current instance on the system, then the data in the new field cannot be maintained when updating the instance through a backwards compatible request. Request data replaces all the data within a list of objects. There is currently no workaround for this issue.

API Version

The API Version is represented in major.minor.revision format, for example: 10.1.2, 10.6.1, 10.6.2, or 10.6.3.

The API Version can be seen in the meta section of the resource as follows:

"meta": {
 "tags": [],
 "pkid": "",
 "schema_version": "0.1",
 "hierarchy": "sys",
 "version_tag": "0.2",
 "api_version": "10.6.1",
 "model_type": "data/DataModel" },

Supported Models and Methods

Supported models are:

  • Data Models
  • Device Models
  • Relations
  • Views

The supported HTTP methods on models from the API are:

  • GET
  • POST
  • PUT

Versions Supported

Support for backwards compatibility was introduced in 10.6(1) release.

  • The 10.6(2) release is backwards compatible with the 10.6(1) release.
  • The 10.6(1) release is backwards compatible with the 10.1(2) release.
  • The 10.6(1) release is not compatible with the 10.1(1) release.
  • The 10.1(2) release is not compatible with the 10.1(1) release.

Specifying the API Version

Third-party API clients must specify the api_version when integrating with VOSS-4-UC 10.6(x). This is required if the third-party client wants to use backwards compatibility, since it ensures that the client continues to receive consistent schemas. Specifying the API version can be done in one of two ways.

In the Query Parameter:

GET http://localhost/api/data/Countries/?hierarchy=[hierarchy]
 &schema=true
 &format=json
 &api_version=10.6.1

The Query Parameter approach is the recommended method for a client to specify the API Version.

In the Request Header:

GET http://localhost/api/data/Countries/?hierarchy=[hierarchy]
&schema=true
&format=json

Request headers
X-Version: 10.6.1

Omitting the API Version

If the API Version is omitted, then the following behavior is expected:

  • If the URL contains /v0/, the 10.1(2) API schemas are used.
  • If the URL does not contain /v0/, the most recent version API schemas are used.