Skip to main content

Installing/Updating an interface

Interfaces are supposed to change over time, and are dynamic. As such, they can be installed and updated. Interface installation means adding either a whole new Interface (as in: an Interface with a new name), or a new major version of an already known Interface. Interface update means updating a specific, existing interface name/major version with a new minor version.

When designing interfaces, it is strongly advised to use Data Orchestrator Interface Editor. The Editor is embedded into any Data Orchestrator Dashboard installation but, in case your Data Orchestrator installation does not provide you with a Dashboard, you can use Data Orchestrator Interface Editor public online instance. Use it to write and validate your definitions, and install the resulting JSON file through either astartectl or Realm Management APIs.

Synchronizing interfaces using astartectl​

astartectl provides a handy sync command that, given a list of Interface files, will synchronize the state of the Data Orchestrator Realm with your local interfaces. It is handy in those cases where your Realm has several interfaces, and you're storing Interfaces in a common place, such as a Git Repository - this is the average case for Data Orchestrator-based applications/clouds.

Assuming you have a set of Interface files in your folder all with the .json extension, invoking astartectl realm-management interfaces sync will result in something like this:

$ astartectl realm-management interfaces sync *.json
Will install interface com.my.Interface1 version 0.2
Will install interface com.my.Interface2 version 1.1
Will update interface com.my.Interface3 to version 1.4

Do you want to continue? [y/n] y
Interface com.my.Interface1 installed successfully
Interface com.my.Interface2 installed successfully
Interface com.my.Interface3 updated successfully to version 1.4

After invocation, your Data Orchestrator Realm will be up to date with all Interfaces in your local directory.

Note: astartectl realm-management interfaces sync currently synchronizes Interfaces only from your local machine to the Realm, and not the other way round. In case the Realm has a more recent version of an interface compared to your local files, or it has some interfaces which are not referenced by your local files, no action will be taken.

Install an Interface using Data Orchestrator Dashboard​

Access the Editor by going to the Interfaces page, and clicking on "Install a New Interface..." in the top-right corner. The Editor will open. From there, you can either paste in an existing JSON definition, which will be validated and will update the left-screen declarative Editor, or you can build a whole new Interface from scratch.

Once you're done, hit the "Install Interface" button at the bottom of the declarative Editor (left side) to install the Interface in the Realm.

Install an Interface using astartectl​

First of all, ensure that you have the Interface you'd like to install saved in a file on your local machine. We will assume the interface is available as interface1.json.

$ astartectl realm-management interfaces install interface1.json
ok

Install an Interface using Realm Management API​

Realm Management currently implements a completely asynchronous API for Interface installation - as such, the only feedback received by the API is that the Interface is valid and the request was accepted by the backend. However, this is no guarantee that the Interface will be installed successfully. As a best practice, it is advised to either wait a few seconds in between Realm Management API invocations, or verify through a GET operation whether the Interface has been installed or not.

POST <astarte base API URL>/realmmanagement/v1/test/interfaces

The POST request must have the following request body, with content type application/json

{
"data": {
"version_minor": 2,
"version_major": 0,
"type": "properties",
"ownership": "device",
"mappings": [
{
"type": "integer",
"path": "/myValue",
"description": "This is quite an important value."
},
{
"type": "integer",
"path": "/myBetterValue",
"description": "A better revision, introduced in minor 2, supported only by some devices"
},
{
"type": "boolean",
"path": "/awesome",
"allow_unset": true,
"description": "Introduced in minor 1, tells you if the device is awesome. Optional."
}
],
"interface_name": "com.my.Interface1"
}
}

The call will return either 201 Created or an error. Most common failure cases are:

  • The interface/major combination already exists in the Realm
  • The interface schema fails validation

In any case, the API returns details on what caused the error and how to solve it through Data Orchestrator's standard error reply schema.

Update an Interface using astartectl​

First of all, ensure that you have the Interface you'd like to update saved in a file on your local machine. We will assume the interface is available as interface1_3.json.

$ astartectl realm-management interfaces update interface1_3.json
ok

Update an Interface using Data Orchestrator Dashboard​

Go to the Interfaces page, click on the Interface Name you'd like to update, and click on the Major version which is referred by your upgrade (e.g.: if you're updating from 1.2 to 1.3, you want to click on Major Version 1). The Editor will appear, populated with the currently installed Interface definition. Paste in your updated JSON file, or use the declarative editor to make your changes. The editor will be limited to Semantic Version-compatible operations (as in - adding new mappings).

Once you're done, hit the "Apply Changes" button at the bottom of the declarative Editor (left side) to update the Interface in the Realm.

Update an Interface using Realm Management API​

To update an existing interface, issue a PUT /interfaces/<name>/<major> endpoint of the realm with the very same semantics as the Installation procedure. The call will return either 201 Created or an error. Apart from the very same errors that could be triggered upon installation, Update will also fail if the interface doesn't provide a compatible upgrade path from the previously installed minor.

Interface update limitations​

Major version updates​

Major version updates have no intrinsic limitations as they are not meant to ensure compatibility with older versions of the same interface. Therefore, if you plan to bump your interface major you are allowed to update your interface at your preference. Please, refer to the Interface Design Guide to follow the best practices while developing your new updated interface.

Minor version updates​

Minor version updates are conceived to guarantee retro-compatibility and, as such, they allows only for a limited subset of update operations.

Currently, based on the interface type and aggregation, different update capabilities are provided:

  • properties:

    • at interface root level, doc and description updates are allowed;
    • at mapping level, doc and description updates are allowed. Moreover, an arbitrary number of new mappings can be added;
  • individual datastream:

    • at interface root level, doc and description updates are allowed;
    • at mapping level, doc, description and explicit_timestamp updates are allowed. Moreover, an arbitrary number of new mappings can be added;
  • object aggregated datastream:

    • currently, due to a limitation in how data are stored within Cassandra, the doc, descriprion and explicit-timestamp fields can not be updated;
    • at mapping level, an arbitrary number of mappings can be added.

Where not explicitly stated, all the other values are to be considered as not updatable. In case you need to update one of those fields, please consider updating your interface major version.