ISY Developers:API:V5:Node Server:REST Support in Node Server

From Universal Devices, Inc. Wiki


ISY_Developers : API : V5 : Node Server : Required REST support in Node Server

General

Each node server is required to support a set of APIs that the ISY will use to manage the nodes being supplied by the node server. Primarily, these APIs are used to add/delete/rename nodes, send commands to nodes, and request node information. Other APIs request the node server to install or upgrade itself on the ISY, and generally manage the configuration of the node server.

Request IDs

<base>/....[?requestId=<requestId>‌]

On most API calls, the ISY can optionally supply a requestId. If a requestId appears on the URL then the node server must send a success or fail message back to the ISY after it has completed the requested action, and, after all messages from that completed action have been sent to the ISY.

This allows the ISY to run a command synchronously. For example, the ISY may need to query a device and use the results of the query to do some additional processing.

Node Addresses

All node addresses are given a prefix assigned by the ISY. The prefix is unique to the node server thus guaranteeing that all node addresses on the ISY are unique.

The format of the node address prefix is:

n‌aaa_

Where aaa is the profile number assigned to the node server in the ISY. A node address is made up of any combination of lowercase letters, numbers, and '_' character.

A node address for profile 5 could look something like:

n005_dimmer_3_1

The dimmer_3_1 portion of the node address is completely defined by the node server or the user creating the node.

The maximum node length (including the prefix) is 19 characters.

Install

<base>/install/<profileNumber>

Instructs the node server to install all the profile files for the node server (rather than having the user do it through the ISY admin console). This is done by removing the old files and then adding all the files one by one, as follows:

  • /rest/ns/<profileNumber>/profile/remove
  • For each file:
    • /rest/ns/<profileNumber>/profile/upload/<dir>/<filename>
  • /rest/ns/<profileNumber>/profile/reload

NOTE: In the current implementation, the ISY must be restarted for the new files to take effect.

Query node

<base>/nodes/<nodeAddress>/query[?requestId=<requestId>‌]

The node server must query the specified node, and send the results to the ISY using the Report Status Rest command.

If a requestId is specified, the status of the request must be sent to the ISY after all other messages are sent.

If a <nodeAddress> of "0" is specified, then all nodes must be queried.

Get Node Status Values

<base>/nodes/<nodeAddress>/status[?requestId=<requestId>‌]

The node server sends the current status values for the specified node to the ISY using the Report Status Rest command.

If a requestId is specified, the status of the request must be sent to the ISY after all other messages are sent.

If a <nodeAddress> of "0" is specified, then statis for all nodes must be sent.

Add All Nodes

<base>/add/nodes[?requestId=<requestId>‌]

Instructs the node server to add all of its nodes to the ISY (see Node Management).

If a requestId is specified, the status of the request must be sent to the ISY after all other messages are sent.

Reports from ISY

Reports provided by the ISY give the node server an opportunity to update its own database of nodes.

<base>/nodes/<nodeAddress>/report/add/<nodeDefId>?primary=<nodeAddress>&name=<nodeName>

- Reports to the node server that the given node was added to the ISY.

<base>/nodes/<nodeAddress>/report/remove

- Reports to the node server that the given node was removed from the ISY.

<base>/nodes/<nodeAddress>/report/rename?name=<nodeName>

- Reports to the node server that the given node was renamed in the ISY.

<base>/nodes/<nodeAddress>/report/enable

- Reports to the node server that the given node was enabled in the ISY.

<base>/nodes/<nodeAddress>/report/disable

- Reports to the node server that the given node was disabled in the ISY.


NOTE: In the future, there may be additional APIs added that allow the node server more control over the actual creation and modification of nodes.

Run a command

<base>/nodes/<nodeAddress>/cmd/<command>
<base>/nodes/<nodeAddress>/cmd/<command>/<value>
<base>/nodes/<nodeAddress>/cmd/<command>/<value>/<uom>

[?‌<p1>.<uom1>=<val1>&<p2>...][requestId=<requestId>‌]

The node server must run the specified command for the specified node. This command may have originated from an ISY program, the standard ISY REST API, the admin console, or any other client. The commands normally sent are those listed in the <accepts> section of the node definition used for the given node.

The numeric value of the UOM is always supplied and is never one of the common names. For example, 51 will be used instead of 'percent'. For parameters in the <pX>.<uomX> format, the numeric uom value is always prefixed by 'uom'

If a requestId is specified, the status of the running the command must be sent to the ISY after the command has completed or failed.

nodeAddress The full address of the node (e.g. 'n005_switch_1)
command The command to perform (e.g. 'DON', 'CLISPH', etc.)
pN Nth Parameter name (e.g. 'level')
uomN Unit of measure of the Nth parameter (e.g. 'uom58')
valN The numeric value of the Nth parameter (e.g. '80', '80.01' etc,)

Commands may also have an unnamed parameter

value The value of the unnamed parameter.
uom Unit of measure of the value of the unnamed parameter (e.g. 51)

E.g.

/myserver/nodes/n005_switch_1/cmd/DON
/myserver/nodes/n005_switch_1/cmd/DON/80/51
/myserver/nodes/n005_switch_1/cmd/DON?level.uom51=80
/myserver/nodes/n005_switch_1/cmd/DON/80/51?rate.uom58=0.3
Retrieved from "https://wiki.universal-devices.com/index.php?title=ISY_Developers:API:V5:Node_Server:REST_Support_in_Node_Server&oldid=8345"