REST

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:

OperationURLDescription
listGET /itemsList all HomeItems
getGET /items/[ItemId]Get a HomeItem
setPUT /items/[ItemId]Update a HomeItem
createPOST /itemsCreate a HomeItem
deleteDELETE /items/[ItemId]Delete a HomeItem
actionPOST /items/[ItemId]/actions/[action]/invokeInvoke an action in a HomeItem
logGET /items/[ItemId]/logFetch log data

1.1 List all HomeItems

URL/rest/items
MethodGET
Version3.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

NameTypeDescriptionRequired
namestringThe name of the HomeItem instanceRequired
idstringThe identity of the HomeItem instanceRequired
categorystringThe 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]
MethodGET
Version3.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:

NameTypeDescriptionRequired
namestringThe name of the HomeItem instanceRequired
idstringThe identity of the HomeItem instanceRequired
classNamestringThe name of the class of the HomeItem instanceRequired
categorystringThe category of the HomeItem instance. The category is one of: "Lamps", "Timers", "Ports", "GUI", "Hardware", "Controls", "Gauges", "Thermometers", "Infrastructure"Required
actionslist of stringActions supported by the HomeItemRequired
attributeslist of attributeList of attributes of the HomeItemRequired

The attribute listing contains names, values and optionally other properties of the attributes. The following fields may be available for each attribute:

NameTypeDescriptionRequired
namestringThe name of the attributeRequired
valuestringThe current value of the attributeRequired
unitstringThe unit of the attribute value, e.g % or m/sOptional
typestringThe data type of the attribute. All attributes are represented as strings, but may have a type used for interpretation of the valueOptional
valueListlist of stringIf the attribute supports a finite list of values, these are listed hereOptional
readOnlybooleanTrue if the attribute value may not be alteredOptional
canInitbooleanTrue if the attribute is normally readOnly, but may be set before the Item is activatedOptional
isDefaultbooleanTrue if this is the default attribute of the ItemOptional

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]
MethodPUT
Version3.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.

NameTypeDescriptionRequired
namestringThe new name of the HomeItem instanceOptional
attributeslist of attribute valueList of attributes of the HomeItemOptional

Attribute values are described as a subset of the attribute only specifying name and value:

NameTypeDescriptionRequired
namestringThe name of the attributeRequired
valuestringThe current value of the attributeRequired

 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
MethodPOST
Version3.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.

NameTypeDescriptionRequired
namestringThe name of the HomeItem instanceRequiered
classNamestringName of the class of the HomeItem to createRequired
attributeslist of attribute valueList of attributes of the HomeItemOptional

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
MethodPUT
Version3.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]
MethodDELETE
Version3.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
MethodGET
Version3.0

 1.7.1 Description

Get log data from the log file connected to the specified HomeItem.

1.7.2 Query Parameters

NameTypeDescriptionRequired
starttime stringStart of the time period to retrieve log values from in the format yyyyMMddHHmmssOptional
stoptime stringStop of the time period to retrieve log values from in the format yyyyMMddHHmmssOptional

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
    ]
]