Devices (devices)

Devices are represented as objects with the following fields

Name	Type	Read Only	Required for Add	Comment
id	integer	yes	no	The device's ID
uid	string	yes (can be set during Add)	no	The device's UID (this is a Unique ID for this device, typically a MAC address)
label	string	no	yes	The device's label
type_id	integer	no	yes	The IceTV device type ID
manufacturer	string	yes	no	The device's manufacturer's name
model	string	yes	no	The device's model

Devices (devices)

NOTE: All examples are shown in XML and JSON support for other formats may be added later.

The devices "Node" covers all device information and includes facilities for Device Types.

URL	Description
devices	Covers the most common usage, this URL returns "device types" and "devices"
devices/types	Allows discovery of recording device types

Get all devices

URL	https://api.icetv.com.au/devices
Method	GET
Query String
Returns	200 OK & Document (XML or JSON)
	401 Unauthorized
	404 Not Found
	415 Unsupported Media Type
	503 Service Unavailable

Request - URL

GET https://api.icetv.com.au/devices?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of response

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE devices SYSTEM "http://iceguide.icetv.com.au/iceguide/devices.dtd">
<devices>
  <type id="11" manufacturer_id="7" manufacturer_name="Topfield" manufacturer_url="" model="TRF-2400" notes="Topfield TRF-2400" can_have_device_sub="0"/>
  <type id="19" manufacturer_id="10" manufacturer_name="Humax" manufacturer_url="" model="HDR 7500T" notes="Humax HDR 7500T" can_have_device_sub="1"/>
  <device id="22" uid="" label="device0" type_id="11" />
  <device id="23" uid="b8:f6:b1:18:54:f5" label="DEVICE1" type_id="19" />
</devices>

JSON - Structure of the response

Name	Type	Description
types	array	All the device's type of the account
devices	array	All the devices of the account

JSON - Example of response

{
  "types": [
    {
      "id": 11,
      "manufacturer_id": 7,
      "manufacturer_name": "Topfield",
      "manufacturer_url": "",
      "model": "TRF-2400",
      "notes": "Topfield TRF-2400",
      "can_have_device_sub": 0
    },
    {
      "id": 19,
      "manufacturer_id": 10,
      "manufacturer_name": "Humax",
      "manufacturer_url": "",
      "model": "HDR 7500T",
      "notes": "Humax HDR 7500T",
      "can_have_device_sub": 1
    }
  ],
  "devices": [
    {
      "id": 22,
      "uid": "",
      "label": "device0",
      "type_id": 11
    },
    {
      "id": 23,
      "uid": "b8:f6:b1:18:54:f5",
      "label": "DEVICE1",
      "type_id": 19
    }
  ]
}

Get a specific device

URL	https://api.icetv.com.au/devices/#
Method	GET
Query String
Returns	200 OK & Document (XML or JSON)
	401 Unauthorized
	404 Not Found
	415 Unsupported Media Type
	503 Service Unavailable

Request - URL

GET https://api.icetv.com.au/devices/23?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of response

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE devices SYSTEM "http://iceguide.icetv.com.au/iceguide/devices.dtd">
<devices>
  <type id="19" manufacturer_id="10" manufacturer_name="Humax" manufacturer_url="" model="HDR 7500T" notes="Humax HDR 7500T" can_have_device_sub="1"/>
  <device id="23" uid="" label="DEVICE1" type_id="19" />
</devices>

JSON - Structure of the response

Name	Type	Description
types	array	Type of the requested device
devices	array	Info of the requested device

Example of response - JSON

{
  "types": [
    {
      "id": 19,
      "manufacturer_id": 10,
      "manufacturer_name": "Humax",
      "manufacturer_url": "",
      "model": "HDR 7500T",
      "notes": "Humax HDR 7500T",
      "can_have_device_sub": 1
    }
  ],
  "devices": [
    {
      "id": 23,
      "uid": "b8:f6:b1:18:54:f5",
      "label": "DEVICE1",
      "type_id": 19
    }
  ]
}

Add a device

URL	https://api.icetv.com.au/devices
Method	POST
Query String
Returns	201 Created & Document (XML or JSON)
	401 Unauthorized
	406 Not Acceptable
	415 Unsupported Media Type
	503 Service Unavailable

A document containing the new device record must be sent as part of the request.

The document to be sent to the server omits the "id" field as this generated by the server.

The document to be sent to the server retains the original "label" field.

The server response will include the newly created device/s as it would appear in a device GET which allows the caller to update there local cache with the device id.

NOTE: Multiple devices can be included in the request, but only one is required.

Request - URL

POST https://api.icetv.com.au/devices?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of request

<devices>
  <device uid="123456" label="DEVICE 0" type_id="12" />
  <device uid="654321" label="DEVICE 1" type_id="12" />
</devices>

XML - Example of response

Location: https://api.icetv.com.au/devices/71.xml 
 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE devices SYSTEM "http://iceguide.icetv.com.au/iceguide/devices.dtd">
<devices>
 <type id="12" manufacturer_id="6" manufacturer_name="Beyonwiz" manufacturer_url="" model="FV-L1" notes="Beyonwiz FV-L1" can_have_device_sub="0" />
 <device id="71" uid="123456" label="DEVICE 0" type_id="12" />
 <device id="72" uid="654321" label="DEVICE 1" type_id="12" />
</devices>

This api supports 2 types of request, you can either send an array of devices or a single device.

JSON - Structure of the request - 1

Name	Type	Description
devices	array	The devices to be added to the account

JSON - Structure of the request - 2

Name	Type	Description
-	table	The device to be added to the account

JSON - Example of request - 1

{
  "devices": [
    {
      "uid": "123456",
      "type_id": "12",
      "label": "DEVICE 0"
    },
    {
      "uid": "654321",
      "type_id": "12",
      "label": "DEVICE 1"
    }
  ]
}

JSON - Example of request - 2

    {
      "uid": "654321",
      "type_id": "12",
      "label": "DEVICE 1"
    }

JSON - Structure of the response - 1

Name	Type	Description
types	array	The types of the devices just added
devices	array	The devices just added

JSON - Structure of the response - 2

Name	Type	Description	Comment
types	array	The type of the device just added	The array will contain one type
devices	array	The device just added	The array will contain one device

JSON - Example of response - 1

{
  "types": [
    {
      "id": 12,
      "manufacturer_id": 6,
      "manufacturer_name": "Beyonwiz",
      "manufacturer_url": "",
      "model": "FV-L1",
      "notes": "Beyonwiz FV-L1",
      "can_have_device_sub": 0
    }
  ],
  "devices": [
    {
      "id": 66,
      "uid": "123456",
      "label": "DEVICE 0",
      "type_id": 12
    },
    {
      "id": 67,
      "uid": "654321",
      "label": "DEVICE 1",
      "type_id": 12
    }
  ]
}

JSON - Example of response - 2

{
  "types": [
    {
      "id": 12,
      "manufacturer_id": 6,
      "manufacturer_name": "Beyonwiz",
      "manufacturer_url": "",
      "model": "FV-L1",
      "notes": "Beyonwiz FV-L1",
      "can_have_device_sub": 0
    }
  ],
  "devices": [
    {
      "id": 67,
      "uid": "654321",
      "label": "DEVICE 1",
      "type_id": 12
    }
  ]
}

Modify a device

URL	https://api.icetv.com.au/devices/#
Method	PUT
Query String
Returns	200 OK
	401 Unauthorized
	406 Not Acceptable
	415 Unsupported Media Type
	503 Service Unavailable

Request - URL

PUT https://api.icetv.com.au/devices/DEVICE_ID?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of request

<devices>
    <device uid="123456789" label="Test 0" type_id="18" />
</devices>

XML - Example of response

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE devices SYSTEM "http://iceguide.icetv.com.au/iceguide/devices.dtd">
<devices>
 <type id="18" manufacturer_id="7" manufacturer_name="Topfield" manufacturer_url="" model="TRF-2460" notes="Topfield TRF-2460" can_have_device_sub="0" />
 <device id="24" uid="123456789" label="Test 0" type_id="18" />
</devices>

JSON - Structure of the request

Name	Type	Description	Comment
-	table	The types of the devices just added	only type_id and label can be changed

JSON - Example of request

{
   "type_id": "18",
   "label": "new_label"
}

JSON - Structure of the response

Name	Type	Description	Comment
types	array	The type of the device just modified	The array will contain one type
devices	array	The device just modified	The array will contain one device

JSON - Example of response

{
  "types": [
    {
      "id": 18,
      "manufacturer_id": 7,
      "manufacturer_name": "Topfield",
      "manufacturer_url": "",
      "model": "TRF-2460",
      "notes": "Topfield TRF-2460",
      "can_have_device_sub": 0
    }
  ],
  "devices": [
    {
      "id": 24,
      "uid": "123456789",
      "label": "new_label",
      "type_id": 18
    }
  ]
}

Delete a device

URL	https://api.icetv.com.au/devices/#
Method	DELETE
Query String
Returns	200 OK
	401 Unauthorized
	405 Method Not Allowed
	406 Not Acceptable
	415 Unsupported Media Type
	503 Service Unavailable

Request - URL

DELETE https://api.icetv.com.au/devices/DEVICE_ID?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN