ISY Developers:API:V5:Node Server:REST Support in ISY
ISY_Developers : API : V5 : Node Server : REST support in ISY
REST is an easy to use URL based command set which allows the developer to communicate with the ISY.
Unless otherwise specified, all REST commands use HTTP GET method.
Notes:
- URL Prefix: /rest/ns/<profileNumber>/
- The profileNumber specified on the URL determines which ISY userid/password will be accepted by the ISY for the request.
- Maximum URL size is 255 bytes
Node Management
/nodes/<nodeAddress>/add/<nodeDefId>?primary=<primary>&name=<nodeName>[&nls=<nlsKey>]
Adds a node to the ISY. To make this node the primary, set primary to the same value as nodeAddress
| nodeAddress | The full address of the node (e.g. 'n005_dimmer_1') |
| nodeDefId | The id of the node definition to use for this node |
| primary | The primary node for the device this node belongs to |
| nodeName | The name of the node |
| nls | (Optional) NLS key string for information specific to this node |
E.g.
| /rest/ns/5/nodes/n005_dimmer_2/add/MyDimmer?primary=n005_dimmer_1&name=Dimmer 2&nls=012B |
/add/nodes
Sends a request to the node server to have it add all of its nodes to the ISY. This API is intended for ISY clients, and is never used by a node server.
E.g.
| /rest/ns/5/add/nodes |
/nodes/<nodeAddress>/change/<nodeDefId>[?nls=<nlsKey>]
Changes the node definition to use for an existing node. An example of this is may be to change a thermostat node from Fahrenheit to Celsius.
| nodeAddress | The full address of the node (e.g. 'n005_dimmer_1') |
| nodeDefId | The id of the node definition to use for this node |
| nls | (Optional) NLS key string for information specific to this node |
E.g.
| /rest/ns/5/nodes/n005_tstat_1/change/ThermostatCelsius?nls=4511 |
/nodes/<nodeAddress>/remove
Removes a node from the ISY. A node cannot be removed if it is the primary node for at least one other node.
| nodeAddress | The full address of the node (e.g. 'n005_dimmer_1') |
E.g.
| /rest/ns/5/nodes/n005_dimmer_2/remove |
/nodes/<nodeAddress>/set/hint/<value>
Adds a hint to the node. This ISY stores the value with the node but does not use this value in any way.
| nodeAddress | The full address of the node (e.g. 'n005_dimmer_1') |
| value | A four byte integer |
E.g.
| /rest/ns/5/nodes/n005_dimmer_2/set/hint/101 |
Reporting status updates
| /nodes/<nodeAddress>/report/status |
| /nodes/<nodeAddress>/report/status/<statusName>/<value>/<uom> |
[?<s1>.<uom1>=<val1>&<s2>.<uom2>=<val2>&<s3>…]
Updates the ISY with the current value of one or more node status values (e.g. the current temperature, light level, etc.)
| nodeAddress | The full address of the node (e.g. 'n005_dimmer_1') |
| statusName, sN | The name of the status value (e.g. 'ST', 'CLIHUM', etc.) |
| value, valN | The numeric status value (e.g. '80.5') |
| uom, uomN | Unit of measure of the status value |
E.g.
| /rest/ns/5/nodes/n005_dimmer_2/report/status/ST/25.2/percent |
| /rest/ns/5/nodes/n005_dimmer_2/report/status?ST.percent=25.2 |
| /rest/ns/2/nodes/n002_tstat_1/report/status/ST/68/17?CLISPC.uom17=76.5&CLISPH.uom17=64 |
| /rest/ns/2/nodes/n002_tstat_1/report/status?ST.uom17=68&CLISPC.uom17=76.5&CLISPH.uom17=64 |
Note: Support for updating multiple status values is not available in builds 5.0.16C or earlier
Reporting a command
| /nodes/<nodeAddress>/report/cmd/<command> |
| /nodes/<nodeAddress>/report/cmd/<command>/<value> |
| /nodes/<nodeAddress>/report/cmd/<command>/<value>/<uom> |
[?<p1>.<uom1>=<val1>&<p2>.<uom2>=<val2>&<p3>…]
Sends a command to the ISY that may be used in programs and/or scenes. A common use of this is a physical switch that somebody turns on or off. Each time the switch is used, a command should be reported to the ISY. These are used for scenes and control conditions in ISY programs.
| 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. 'seconds', '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.
| /rest/ns/5/nodes/n005_switch_1/report/cmd/DON |
| /rest/ns/5/nodes/n005_switch_1/report/cmd/DON/80/percent |
| /rest/ns/5/nodes/n005_switch_1/report/cmd/DON?level.percent=80 |
| /rest/ns/5/nodes/n005_switch_1/report/cmd/DON/80/percent?rate.uom58=0.3 |
Reporting ISY Request status
| /report/request/<requestId>/success |
| /report/request/<requestId>/failed |
| /report/request/<requestId>/unsupported |
When the ISY sends a request to the node server, the request may contain a requestId field. This indicates to the node server that when the request is completed, it must send a fail or success report for that request. This allows the ISY to in effect, have the node server synchronously perform tasks. This message must be sent after all other messages related to the task have been sent.
For example, if the ISY sends a request to query a node, all the results of the query must be sent to the ISY before a fail/success/unsupported report is sent.
| requestId | The request ID the ISY supplied on a request to the node server. |
E.g.
| /rest/ns/5/report/request/1234/success |