REST API: Devices

GET devices

Description: Returns all devices
URL: GET /devices.<format>
Formats: xml
Requires Authentication: Yes*
Specific Error States:

• None.

Usage Examples:

curl -u user:pass http://localhost:8080/devices.xml
<?xml version="1.0" encoding="UTF-8"?>
<devices>
<device id="1">
		<name>KitchenLight</name>
		<protocol>arctech</protocol>
		<model>selflearning-dimmer:nexa</model>
		<lastcmd>ON</lastcmd>
		<supportedMethod id="2">TELLSTICK_TURNOFF</supportedMethod>
		<supportedMethod id="1">TELLSTICK_TURNON</supportedMethod>
		<supportedMethod id="16">TELLSTICK_DIM</supportedMethod>
		<supportedMethod id="32">TELLSTICK_LEARN</supportedMethod>
</device>
<device id="5">
		<name>OutdoorLight</name>
		<protocol>arctech</protocol>
		<model>codeswitch</model>
		<lastcmd>ON</lastcmd>
		<supportedMethod id="2">TELLSTICK_TURNOFF</supportedMethod>
		<supportedMethod id="1">TELLSTICK_TURNON</supportedMethod>
</device>
</devices>

POST devices

Description: Creates a new device
URL: POST /devices.<format>
Formats: xml
Requires Authentication: Yes*
Parameters:
name – required. Specifies the name.
model – required. Specifies the model.
protocol – required. Specifies the protocol.
parameters – optional. Adds parameters to the device. Space delimited key=value pair. Note that these parameters could be required for the device to function properly.
Specific Error States:

1. 400 (HTTP) 201 (ERROR) if parameter name not supplied.
2. 400 (HTTP) 202 (ERROR) if parameter model not supplied.
3. 400 (HTTP) 203 (ERROR) if parameter protocol not supplied.
4. 400 (HTTP) 210 (ERROR) if parameter parameters is malformed.

Usage Examples:

curl -u user:pass -d "name=Bedroom&model=codeswitch&protocol=arctech&parameters=house=A unit=1" http://localhost:8080/devices.xml
<?xml version="1.0" encoding="UTF-8"?>
<device id="14">
		<name>Bedroom</name>
		<protocol>arctech</protocol>
		<model>codeswitch</model>
		<lastcmd>OFF</lastcmd>
		<supportedMethod id="2">TELLSTICK_TURNOFF</supportedMethod>
		<supportedMethod id="1">TELLSTICK_TURNON</supportedMethod>
</device>

*) Authentication is required if remotestick-server has been passed a username and password upon startup.

GET device

Description: Returns the specified device
URL: GET /devices/<id>.<format>
Formats: xml
Requires Authentication: Yes*
Specific Error States:

1. 400 (HTTP) 210 (ERROR) if the id is malformed.

Usage Examples:

curl -u user:pass http://localhost:8080/devices/1.xml
<?xml version="1.0" encoding="UTF-8"?>
<device id="1">
		<name>KitchenLight</name>
		<protocol>arctech</protocol>
		<model>selflearning-dimmer:nexa</model>
		<lastcmd>ON</lastcmd>
		<supportedMethod id="2">TELLSTICK_TURNOFF</supportedMethod>
		<supportedMethod id="1">TELLSTICK_TURNON</supportedMethod>
		<supportedMethod id="16">TELLSTICK_DIM</supportedMethod>
		<supportedMethod id="32">TELLSTICK_LEARN</supportedMethod>
</device>

Note: This method does not currently notify the client whether or not the resource exists or not. This is due to such support from libtelldus library. remotestick-server will perhaps solve this in the future by iterating over the complete set of devices to see if the id exists.

DELETE device

Description: Deletes the specified device
URL: DELETE /devices/<id>.<format>
Formats: xml
Requires Authentication: Yes*
Specific Error States:

1. 400 (HTTP) 210 (ERROR) if the id is malformed.
2. 400 (HTTP) 211 (ERROR) if the device could not be removed.

Usage Examples:

PUT device

Description: Modifies an existent device
URL: PUT /devices.<format>
Formats: xml
Requires Authentication: Yes*
Parameters:
name – optional. Specifies the name.
model – optional. Specifies the model.
protocol – optional. Specifies the protocol.
Specific Error States:

1. 400 (HTTP) 210 (ERROR) if the id is malformed.

Usage Examples:
Note: Due to lacking support in libtelldus-core it is probably only meaningful to use this method to change the name of the device as it is currently not possible to modify the parameters. In such cases, remove the device first and create a new one.

*) Authentication is required if remotestick-server has been passed a username and password upon startup.