Querying Interfaces
Listing Interfaces
You can list all installed interfaces in a given Realm. This will return all the valid installed Interface names, without any versioning.
List Interfaces using astartectl
$ astartectl realm-management interfaces list
[com.my.Interface1 com.my.Interface2 com.my.Interface3]
List Interfaces using Data Orchestrator Dashboard
From your Dashboard, after logging in, click on "Interfaces" in the left menu.
List Interfaces using Realm Management API
GET <astarte base API URL>/realmmanagement/v1/test/interfaces
{"data": ["com.my.Interface1","com.my.Interface2","com.my.Interface3"]}
Listing Major Versions for an Interface
For each installed Interface, there can be any number of Major versions installed. This information can be retrieved by listing the available Major versions for a specific interface.
In a realm, only the latest minor version of each major version of an Interface is kept. This can be done due to the fact that Semantic Versioning implies a new minor version doesn't introduce any breaking change (e.g.: deleting or renaming a mapping), and as such querying an older version of an interface using a newer one as a model is always compatible - some mappings might be empty, as expected, and will be disregarded. Data Orchestrator ensures upon Interface installation for this constraint, and as such you can always query the latest minor version of an Interface safely.
List Versions using astartectl
$ astartectl realm-management interfaces versions com.my.Interface1
[0 1 2]
List Versions using Data Orchestrator Dashboard
In the Dashboard's Interface page, click on any Interface name. A drop-down will appear, showing installed major versions for that Interface name.
List Versions using Realm Management API
GET <astarte base API URL>/realmmanagement/v1/test/interfaces/com.my.Interface1
{"data": [0,1,2]}
Getting an Interface Definition
Data Orchestrator allows you to retrieve the Interface Definition for a given Name and Major Version pair. The definition is in the standard Interface JSON format.
Get Interface Definition using astartectl
$ astartectl realm-management interfaces show com.my.Interface1 0
{
"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"
}
}
Get Interface Definition using Data Orchestrator Dashboard
From the Interfaces page, click on an Interface name, and click on the Major version for which you'd like to see the definition. The Interfaces Editor window will open, with the Interface definition in the text box on the right. From the Editor page, it is also possible to add new mappings to the Interface and bump it to a new Minor.
Get Interface Definition using Realm Management API
GET <astarte base API URL>/realmmanagement/v1/test/interfaces/com.my.Interface1/0
{
"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"
}
}