Interfaces¶

Interface Data Structure¶

An interface is the connection between an instance of a driver and a device. Devices can have any number of interfaces, and each interface is connected to exactly one driver.

In responses, an interface looks like this:

{
  "opts": {
    "network_session_key": "",
    "managed": true,
    "eui": "",
    "enabled": true,
    "duplicate_framecounter_allowed": true,
    "device_type": "otaa",
    "device_key": "",
    "device_eui": "",
    "device_address": "",
    "app_session_key": ""
  },
  "id": "68e8e794-1abe-45d6-a63e-158ed5d611ef",
  "driver_instance_id": "9cf80c6a-1669-4cbf-96d0-9eefb707d294",
  "device_id_or_slug": "43b5dca3-e7d9-4028-9309-c26ac0c08721"
}

Key	Example	Description
`id`	`68e8e794-1abe-45d6-a63e-158ed5d611ef`	Unique interface ID (UUID4)
`opts`	`{"enabled": true, "duplicate_framecounter_allowed": true, "device_type": "otaa"}`	A JSON object containing all relevant configuration options
`device_id_or_slug`	`43b5dca3-e7d9-4028-9309-c26ac0c08721`	Reference to the device this interface belongs to
`driver_instance_id`	`9cf80c6a-1669-4cbf-96d0-9eefb707d294`	Reference to the device this interface belongs to

Configuration Options¶

Depending on the driver being used, a number of configuration options may be provided. Please refer to the driver documentation for details.

List all Interfaces¶

Method: GET, Endpoint: /devices/:device_id_or_slug/interfaces

Example Request¶

GET https://element-iot.com/api/v1/devices/test-device/interfaces?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "retrieve_after_id": "a70a234e-d186-4ca8-836b-74816738939e",
  "ok": true,
  "body": [
    // Contains an array of interfaces
  ]
}

This endpoint returns a paginated list of interfaces.

If you want to configure the sort order or restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

Show a single Interface¶

Method: GET, Endpoint: /devices/:device_id_or_slug/interfaces/:interface_id

Example Request¶

GET https://element-iot.com/api/v1/devices/test-device/interfaces/489e4524-12e3-4e96-a438-758dce9efeb6?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the interface
  }
}

The device ID may be either the id or the slug of the device. The interface ID must be the id of the interface.

Create a new Interface¶

Method: POST, Endpoint: /devices/:device_id_or_slug/interfaces

Example Request¶

POST https://element-iot.com/api/v1/devices/test-device/interfaces?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "interface": {
    "name": "New Interface Name",
    "type": "sensor"
  }
}

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the new interface
  }
}

Parameters

Encapsulate all parameters to be changed in a interface object in the request body.

The device ID may be either the id or the slug of the device. The interface ID must be the id of the interface.

Edit single Interface¶

Method: PUT or PATCH, Endpoint: /devices/:device_id_or_slug/interfaces/:interface_id

Example Request¶

PUT https://element-iot.com/api/v1/devices/test-device/interfaces/489e4524-12e3-4e96-a438-758dce9efeb6?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "interface": {
    "name": "New Name",
    "color_hue": 40
  }
}

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the changed interface
  }
}

Parameters

Encapsulate all parameters to be changed in a interface object in the request body.

The device ID may be either the id or the slug of the device. The interface ID must be the id of the interface.

Delete single Interface¶

Method: DELETE, Endpoint: /devices/:device_id_or_slug/interfaces/:interface_id

Example Request¶

DELETE https://element-iot.com/api/v1/devices/test-device/interfaces/489e4524-12e3-4e96-a438-758dce9efeb6?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response¶

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the deleted interface
  }
}

The device ID may be either the id or the slug of the device. The interface ID must be the id of the interface.