View source for ISY Developers:API:V5:Node Server:REST Support in ISY

<!--
   ** DO NOT EDIT ON THE WIKI WEBSITE - Source file is v5.nodeServer.restSupportInIsy.wiki.txt **
 -->

[[ISY_Developers]] : [[ISY_Developers:API | API]] : [[ISY_Developers:API:V5 | V5]] : [[ISY_Developers:API:V5:Node_Server | Node Server]] : REST support in ISY

__TOC__

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.

See [[ISY_Developers:API:V5:REST:Return_Codes | REST return codes]]

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.
{| style="font-family: courier;"
|/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.
{| style="font-family: courier;"
|/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.
{| style="font-family: courier;"
|/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.
{| style="font-family: courier;"
|/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.
{| style="font-family: courier;"
|/rest/ns/5/nodes/n005_dimmer_2/set/hint/101
|}

==Reporting status updates==

{|
|/'''nodes'''/''<nodeAddress>''/'''report'''/'''status'''
|-
|/'''nodes'''/''<nodeAddress>''/'''report'''/'''status'''/''<statusName>''/''<value>''/''<uom>''
|}

'''[?'''&zwnj;''<s1>.<uom1>=<val1>&<s2>.<uom2>=<val2>&<s3>…''&zwnj;''']'''

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.
{| style="font-family: courier;"
|/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>''
|}

'''[?'''&zwnj;''<p1>.<uom1>=<val1>&<p2>.<uom2>=<val2>&<p3>…''&zwnj;''']'''

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.
{| style="font-family: courier;"
|/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.
{| style="font-family: courier;"
|/rest/ns/5/report/request/1234/success
|}