The REST interface is part of the JettyWEB HomeItem, so the address is the same as for the web interface. This means that if the WEB interface in a OpenNetHome installation for example is on http://192.168.1.110:8020/home, the the REST call to list all home items would be on http://192.168.1.110:8020/rest/items
1. HomeItem API
Since OpenNetHome is designed around the HomeItem abstraction, the Items-API can control most of the behavior of the OpenNetHome-server. The interface exposes the HomeItems as REST-resources.
The HomeItem API consists of the following requests:
Operation | URL | Description |
---|---|---|
list | GET /items | List all HomeItems |
get | GET /items/[ItemId] | Get a HomeItem |
set | PUT /items/[ItemId] | Update a HomeItem |
create | POST /items | Create a HomeItem |
delete | DELETE /items/[ItemId] | Delete a HomeItem |
action | POST /items/[ItemId]/actions/[action]/invoke | Invoke an action in a HomeItem |
log | GET /items/[ItemId]/log | Fetch log data |
1.1 List all HomeItems
URL | /rest/items |
Method | GET |
Version | 3.0 |
1.1.1 Description
Gets a list of all HomeItems in the system.
1.1.2 Response
Returns a list of directory entries for all HomeItems in the system
Name | Type | Description | Required |
---|---|---|---|
name | string | The name of the HomeItem instance | Required |
id | string | The identity of the HomeItem instance | Required |
category | string | The category of the HomeItem instance. The category is one of: "Lamps", "Timers", "Ports", "GUI", "Hardware", "Controls", "Gauges", "Thermometers", "Infrastructure" | Required |
1.1.3 Response example
[ { "name": "Audio", "id": "75", "category": "Hardware" }, { "name": "Bed Room", "id": "33", "category": "Infrastructure" }, { "name": "Bedroom Lamp", "id": "56", "category": "Lamps" }, { "name": "Button", "id": "83", "category": "Controls" }, { "name": "CommandPort", "id": "109", "category": "Ports" }, { "name": "DayLogger", "id": "106", "category": "Gauges" } ] |
1.2 Get HomeItem
URL | /rest/items/[ItemId] |
Method | GET |
Version | 3.0 |
1.2.1 Description
Get the content of the specified HomeItem
1.2.2 Response
Returns the name, id, category, class, attributes and actions of the specified HomeItem:
Name | Type | Description | Required |
---|---|---|---|
name | string | The name of the HomeItem instance | Required |
id | string | The identity of the HomeItem instance | Required |
className | string | The name of the class of the HomeItem instance | Required |
category | string | The category of the HomeItem instance. The category is one of: "Lamps", "Timers", "Ports", "GUI", "Hardware", "Controls", "Gauges", "Thermometers", "Infrastructure" | Required |
actions | list of string | Actions supported by the HomeItem | Required |
attributes | list of attribute | List of attributes of the HomeItem | Required |
The attribute listing contains names, values and optionally other properties of the attributes. The following fields may be available for each attribute:
Name | Type | Description | Required |
---|---|---|---|
name | string | The name of the attribute | Required |
value | string | The current value of the attribute | Required |
unit | string | The unit of the attribute value, e.g % or m/s | Optional |
type | string | The data type of the attribute. All attributes are represented as strings, but may have a type used for interpretation of the value | Optional |
valueList | list of string | If the attribute supports a finite list of values, these are listed here | Optional |
readOnly | boolean | True if the attribute value may not be altered | Optional |
canInit | boolean | True if the attribute is normally readOnly, but may be set before the Item is activated | Optional |
isDefault | boolean | True if this is the default attribute of the Item | Optional |
1.2.3 Response example
{ "name": "Bedroom Lamp", "id": "56", "className": "NexaLCLamp", "category": "Lamps", "actions": [ "toggle", "on", "off" ], "attributes": [ { "name": "State", "value": "Off", "readOnly": true, "default": true }, { "name": "Address", "value": "938457" }, { "name": "Button", "value": "1" }, { "name": "TransmissionRepeats", "value": "" } ] } |
1.3 Set HomeItem attribute values (rename)
URL | /rest/items/[ItemId] |
Method | PUT |
Version | 3.0 |
1.3.1 Description
Update the attribute values and possibly the name of the specified HomeItem
1.3.2 Body arguments
Note that only supplied attributes are updated. Omitting to supply an attribute value does not alter the state of the HomeItem. It is allowed to supply all properties of the HomeItem resource, but everything except attribute values and instance name will be ignored.
Name | Type | Description | Required |
---|---|---|---|
name | string | The new name of the HomeItem instance | Optional |
attributes | list of attribute value | List of attributes of the HomeItem | Optional |
Attribute values are described as a subset of the attribute only specifying name and value:
Name | Type | Description | Required |
---|---|---|---|
name | string | The name of the attribute | Required |
value | string | The current value of the attribute | Required |
1.3.3 Body arguments example
{ "name": "Lamp 3", "attributes": [ { "name": "Address", "value": "938457" }, { "name": "TransmissionRepeats", "value": "17" } ] } |
1.3.4 Response
A complete HomeItem is returned with the resulting state after applying the changes. See 1.2 Get HomeItem for details.
1.4 Create HomeItem
URL | /rest/items |
Method | POST |
Version | 3.0 |
1.4.1 Description
Create a new HomeItem instance. By default the HomeItem is activated as part of this operation. If however the instance name starts with “#”, the new instance is not activated and this has to be made later with an explicit call to the “activate”-action.
1.4.2 Body arguments
Any attribute values not supplied will assume default values from the HomeItem.
Name | Type | Description | Required |
---|---|---|---|
name | string | The name of the HomeItem instance | Requiered |
className | string | Name of the class of the HomeItem to create | Required |
attributes | list of attribute value | List of attributes of the HomeItem | Optional |
Attribute values are the same as described in 1.3.
1.4.3 Body argument example
{ "name": "Test Lamp", "className": "NexaLCLamp", "attributes": [ { "name": "Address", "value": "6111" }, { "name": "Button", "value": "1" }, { "name": "TransmissionRepeats", "value": "17" } ] } |
1.4.4 Response
The complete HomeItem is returned with the resulting state after creating the instance. See 1.2 Get HomeItem for details.
1.5 Invoke HomeItem action
URL | /rest/items/[ItemId]/action/invoke |
Method | PUT |
Version | 3.0 |
1.5.1 Description
Invoke the specified action in the HomeItem
1.5.2 Body arguments
The argument is a single string with the name of the action to invoke
1.5.3 Response
The complete HomeItem is returned with the resulting state after invoking the action. See 1.2 Get HomeItem for details.
1.6 Delete HomeItem
URL | /rest/items/[ItemId] |
Method | DELETE |
Version | 3.0 |
1.6.1 Description
Delete the specified HomeItem instance
1.6.2 Response
No data is returned
1.7 Get HomeItem log data
URL | /rest/items/[ItemId]/log |
Method | GET |
Version | 3.0 |
1.7.1 Description
Get log data from the log file connected to the specified HomeItem.
1.7.2 Query Parameters
Name | Type | Description | Required |
---|---|---|---|
start | time string | Start of the time period to retrieve log values from in the format yyyyMMddHHmmss | Optional |
stop | time string | Stop of the time period to retrieve log values from in the format yyyyMMddHHmmss | Optional |
1.2.2 Response
Returns a list of lists, where the inner list always have two members: the time of the log entry and the value of the log entry.
1.2.3 Response example
[ [ "2014-09-20 01:00", 15.1 ], [ "2014-09-20 01:15", 14.9 ], [ "2014-09-20 01:30", 14.9 ], [ "2014-09-20 01:45", 14.9 ], [ "2014-09-20 02:00", 15 ], [ "2014-09-20 02:15", 14.9 ], [ "2014-09-20 15:00", 22.4 ], [ "2014-09-20 15:15", 21.2 ] ] |