# API useful features

This page shows several useful API features. The API can be accessed through the
[Unwired Edge Cloud Console Developer Tools](https://admin.wifi.unwired.at/developer/playground).

## 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_id``` for that node
    - important: 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:
```json
{
  "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:
```json
{
  "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](https://github.com/jqlang/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](https://github.com/jqlang/jq) installed:

```bash
$ 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:

```bash
$ 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"
      }
    ]
  }
}
```