API useful features
This page shows several useful API features. The API can be accessed through the Unwired Edge Cloud Console Developer Tools.
Data model for device management
Devices are owned by customers and organized in groups. You can consider groups to behave like folders in a file system and devices to be like files.
Hint
Understanding this structure is very helpful in understanding the API queries
Customers have:
a name
a customer_id to uniquely identify the customer
a list of one or more root groups, those are the top-level groups that can hold devices
Groups:
can contain devices
can contain other groups
Nodes:
devices are nodes
groups are nodes
whenever you see a node_id, this can directly refer to:
a device, so it is equivalent to a mac in this case
a group, so you can also query the
group_idfor that nodeimportant: the node_id is not the group_id
Example:
Customer “Rail Demo Customer”
identified by customer_id: “102e88a2-86cf-4a2d-8712-99e8e652db48”
has two root groups:
group “Rail Access Points”
identified by group_id: “60000123”
has a single device:
device name “Main Access Point”
device MAC “4A000102030405”
group “Rail Routers”
identified by group_id: “60000124”
has a single device:
device name “Main Router”
device MAC “4A000102030406”
Getting a list of customers your user has access to
query all_customers {
Authz_customers {
customer_id
}
}
returns a JSON response with all customer IDs:
{
"data": {
"Authz_customers": [
{
"customer_id": "00000000-0000-0000-0000-000000000001"
}
]
}
}
Getting a list of root group IDs of a customer
query root_groups_for_customer {
Authz_group_ids_by_customer_ids(customer_ids: ["102e88a2-86cf-4a2d-8712-99e8e652db48"], recursive: false)
}
returns a JSON response with all group IDs:
{
"data": {
"Authz_group_ids_by_customer_ids": [
"60000123",
"60000124"
]
}
}
Getting a list of device MACs and group IDs
This works for a single or multiple groups. The groups can be root groups (as in top-level) or just any arbitrary group in the group tree. The recursive parameter allows to query up to a certain depth in the tree, or if -1 is provided, it will query all levels available.
query devices_in_groups {
DM_get_nodes_by_group_ids(group_ids: ["500002825"], recursive: -1) {
name
...on DM_Device {
mac
}
...on DM_GroupConfig {
group_id
}
}
}
returns a JSON response with all devices and groups:
devices have MAC addresses
groups have a group_id
{
"data": {
"DM_get_nodes_by_group_ids": [
{
"name": "Rail Access Points",
"group_id": "60000123"
},
{
"name": "Main Access Point",
"mac": "4A000102030405"
},
{
"name": "Rail Routers",
"group_id": "60000124"
},
{
"name": "Main Router",
"mac": "4A000102030406"
}
]
}
}
Hint
JSON can easily be processed for further use by using the helpful jq utility
For example storing the result from above in a file called devices.json, the following will work in any shell (e.g. Linux, MacOS, Linux subsystem for Windows) with jq installed:
$ cat devices.json | jq '.data.DM_get_nodes_by_group_ids[] | select(.mac != null) | .mac'
"4A000102030405"
"4A000102030406"
To get the same list as a comma separated list of macs, use this:
$ cat devices.json | jq '.data.DM_get_nodes_by_group_ids[] | select(.mac != null) | .mac' | awk -v d="," '{s=(NR==1?s:s d)$0}END{print s}'
"4A000102030405","4A000102030406"
Query only a specific sub group
This will query only the routers group:
query devices_in_groups {
DM_get_nodes_by_group_ids(group_ids: ["60000124"], recursive: -1) {
name
...on DM_Device {
mac
}
...on DM_GroupConfig {
group_id
}
}
}
returns a JSON response with all devices and groups below the “Rail Routers” group:
devices have MAC addresses
groups have a group_id
{
"data": {
"DM_get_nodes_by_group_ids": [
{
"name": "Rail Routers",
"group_id": "60000124"
},
{
"name": "Main Router",
"mac": "4A000102030406"
}
]
}
}