Codecore Logo
Quick Search
»
Advanced Search »

HTTP API (RESTful Web Service)

RSS
A simple to use web interface for 3rd parties is available for retrieving system information and controlling the system. For a more feature rich interface that uses a persistant tcp connection to provide on demand system state change notifications, please see the TCP Communication Protocol documentation.


Quick Examples

Here are a few quick examples of how to use this interface. You can enter these URL's directly into a web browser. More details on how these URLS work will be described later in this document.

  • Get the current temperature from the weather device
    http://masterserver:33900/devices/weather/properties/temperature

  • Get the state of UPB light #5
    http://masterserver:33900/devices/upb/properties/lightlevels/index/5

  • Run a script
    http://masterserver:33900/RunScript/false/ubp.TurnOffLight(5);

These urls can be used from a web browser or done programmatically.

Authentication

Authentication is required using a valid username and password via Basic HTTP Authentication. When using a web browser, you will be asked to enter your username and password.

The user account must have the appropriate account setting to gain access to this web service. This is done by editing a user account from the Elve Management Studio application..

Each web service call has it's own authentication requirement as follows:

  • Remote Access
    Access to the web service call is restricted to Elve user accounts which have 3rd party remote access and control access enabled.

  • System Operator Minimum
    Access to the web service call is restricted to Elve user accounts with an account type set to System Operator or Administrator.

Device Control and Information

Get Configuration Time Stamp

Get the last time the configuration was saved.

HTTP Method: GET

URL Syntax: /Configuration/TimeStamp

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Configuration/TimeStamp

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>datetime</type>
  <value>2011-01-14 02:06:47Z</value>
</result>

Get All Device Information

Get the basic details about all devices.

HTTP Method: GET

URL Syntax: /Configuration/Devices

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Configuration/Devices

Example Response:

See the Get Device Information command for a sample response of a single device. The command will return multiple Device elements.

Get Device Information

Get the basic details about a specific device. Device Information generally remains static over the device's lifetime. This does not contain any state information which normally changes during the the device's lifetime.

HTTP Method: GET

URL Syntax: Configuration/Devices/{deviceName}

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Configuration/Devices/lighting

Example Response:


<?xml version="1.0" encoding="utf-8"?>
<Config>
  <Device Name="lighting" Driver="ViziaRFDriver" Enabled="true" DisplayName="Z-Wave (ViziaRF RZC0P)" Status="0">
    <Interface Name="ILightingAndElectricalDriver">
      <Lights FirstID="2" LastID="9">
        <Light ID="2" Name="Garage" />
        <Light ID="3" Name="Kitchen" />
        <Light ID="4" Name="Foyer" />
        <Light ID="5" Name="Laundry" />
        <Light ID="6" Name="Pantry" />
        <Light ID="7" Name="Dining Room" />
        <Light ID="8" Name="Patio" />
        <Light ID="9" Name="Porch" />
      </Lights>
    </Interface>
  </Device>
</Config>

Get All Device States

Get the current state of all devices.

HTTP Method: GET

URL Syntax: DeviceStates

Required User Access: Remote Access

Example Request:

http://masterserver:33900/DeviceStates

Example Response:

See the Get Device State command for a sample response of a single device. The DeviceStates command will return multiple Device elements.

Get Device State

Get the current state of a specified device.

HTTP Method: GET

URL Syntax: DeviceStates/{deviceName}

Required User Access: Remote Access

Example Request:

http://masterserver:33900/DeviceStates/lighting

Example Response:


<?xml version="1.0" encoding="utf-8"?>
<States>
  <Device Name="lighting" Enabled="true" Status="0">
    <Lights>
      <Light ID="2" Level="0" />
      <Light ID="3" Level="0" />
      <Light ID="4" Level="0" />
      <Light ID="5" Level="50" />
      <Light ID="6" Level="0" />
      <Light ID="7" Level="100" />
      <Light ID="8" Level="0" />
      <Light ID="9" Level="0" />
    </Lights>
  </Device>
</States>

Device Status Response Value:

  • 0 : The device is running.
  • 1 : The device's Enabled setting is set to false, meaning it's disabled.
  • 2 : The device attempted to start but failed.
  • 3 : The driver service that the device runs in is not connected.
  • 4 : The device's driver does not exist (like it's driver file (dll) got removed or it's name changed).

Get Device Property Value

Get the value of a device's property.

HTTP Method: GET

URL Syntax: /Devices/{deviceName}/Properties/{propertyName}

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Devices/lighting/Properties/DeviceDisplayName

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>string</type>
  <value>Z-Wave (ViziaRF RZC0P)</value>
</result>

Get Indexed Device Property Value

  • Get the value of an indexed device property.

HTTP Method: GET

URL Syntax: /Devices/{deviceName}/Properties/{propertyName}/Index/{propertyIndex}

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Devices/lighting/Properties/LightLevels/Index/2

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>number</type>
  <value>100</value>
</result>

Set Device Property Value

Set the value of a device's property.

HTTP Method: GET

URL Syntax: /Devices/{deviceName}/Properties/{propertyName}/ValueType/{valueType}/SetValue/{value}

deviceName : The name of the device.
propertyName : The name of the property.
valueType : The datatype of the specified value. Must be one of: string, number, boolean, datetime, or bytearray.
value : The string formated value to set the property to.

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Devices/vars/Properties/mycode/ValueType/string/SetValue/ABC123

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<success>The property was set.</success>

Set Indexed Device Property Value

Set the value of an indexed device property.

HTTP Method: GET

URL Syntax: /Devices/{deviceName}/Properties/{propertyName}/Index/{propertyIndex}/ValueType/{valueType}/SetValue/{value}

deviceName : The name of the device.
propertyName : The name of the property.
propertyIndex : The numberic property index.
valueType : The datatype of the specified value. Must be one of: string, number, boolean, datetime, or bytearray.
value : The string formated value to set the property to.

Required User Access: Remote Access

Example Request:

http://masterserver:33900/Devices/lighting}/Properties/LightLevels/Index/2/ValueType/number/SetValue/50

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<success>The property was set.</success>

Run Script (GET)

Runs a script.

HTTP Method: GET

URL Syntax: /RunScript/{runAsyncronously}/{script}

runAsynchronously : Indicates if the server should wait for the script to complete running and return the result. Must be one of: true or false.
script : The url encoded script to run.

For a script such as:

lighting.SetLightLevel(1, 100);

The url encoded script would look like:

lighting.SetLightLevel%281,%20100%29;

Required User Access: Remote Access

Example Request:

http://masterserver:33900/RunScript/false/lighting.SetLightLevel%281,%20100%29;

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>null</type>
  <value></value>
</result>

Run Script (POST)

Runs a script.

HTTP Method: POST

URL Syntax: /RunScript?RunAsyncronously={runAsyncronously}

runAsynchronously : Indicates if the server should wait for the script to complete running and return the result. Must be one of: true or false.

The post payload should be the script and should NOT be url encoded as with the HTTP GET variant of RunScript.

Example Request:

http://masterserver:33900/RunScript?RunAsyncronously=false

With post data of:

return 1;

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>number</type>
  <value>1</value>
</result>

Configuration

Disable Device

Disable a device and stop it if it is running.

HTTP Method: GET

URL Syntax: /admin/Devices/Disable?devicename={deviceName}

deviceName : The name of the device to disale.

Required User Access: System Operator Minimum

Example Request:

http://masterserver:33900/admin/Devices/Disable?devicename=lighting

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<success>The device named 'lighting' was disabled.</success>

Enable Device

Enable a device and start it if the associated driver service is running.

HTTP Method: GET

URL Syntax: /admin/Devices/Enable?devicename={deviceName}

deviceName : The name of the device to remove.

Required User Access: System Operator Minimum

Example Request:

http://masterserver:33900/admin/Devices/Enable?devicename=lighting

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<success>The device named 'lighting' was enabled.</success>

Remove Device

Remove a device and stop it if it is running.

HTTP Method: GET

URL Syntax: /admin/Devices/Remove?devicename={deviceName}

deviceName : The name of the device to remove.

Required User Access: System Operator Minimum

Example Request:

http://masterserver:33900/admin/Devices/Remove?devicename=lighting

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<success>The device named 'lighting' was removed.</success>

Save Device

Saves a device and starts it if it is enabled.

HTTP Method: GET

URL Syntax: /admin/Devices/Save?devicename={newDeviceName}&drivertypename={driverTypeName}&scriptingidentifieraliases={scriptingIdentifierAliases}&displayname={displayName}&serverName={serverName}&enabled={enabled}&loggingverbosity={verbosity}

newDeviceName : The unique identifier name of the device which the device can be referenced by in scripts.
driverTypeName : The short type name of the driver class. Do not include the namespace.
scriptingIdentifierAliases : A comma delimited list of alias device names. This can be blank.
displayName : Any display name or description of the device.
serverName : The NetBIOS computer name of the Windows machine that this device should run on. A blank value will run on the master service.
enabled : Indicates if the device is enabled. Devices which are not enabled will not be run. The value must be one of true or false.
verbosity : Indicates the logging verbosity that the device should use. This is usually Normal or Diagnostics. The value must be one of Quiet, Minimal, Normal, Detailed, Diagnostic.

Optional Parameters:

originaldevicename : This is an optional parameter. The name of the device to replace.
Any additional query string parameters are assumed to be device settings.

Required User Access: System Operator Minimum

Example Request:

http://masterserver:33900/admin/Devices/Save?devicename=lighting&drivertypename=ViziaRFDriver&scriptingidentifieraliases=&displayname=ZWave+Lighting&serverName=}&enabled=true&loggingverbosity=Normal&SerialPortName=COM1

Example Response:


<?xml version="1.0" encoding="UTF-8"?>
<success>The device named 'lighting' was saved.</success>

Responses

Responses from web service requests will have a content-type of 'text/xml'.

Value Responses

Some web service requests return a value type and value as follows:

String:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>string</type>
  <value>Hello World</value>
<result>

Number:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>number</type>
  <value>1</value>
</result>

Boolean:

The value will be one of true or false.


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>boolean</type>
  <value>true</value>
</result>


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>boolean</type>
  <value>false</value>
</result>

DateTime:

The value will be in ISO 8601 format in Coordinated Universal Time (UTC).


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>datetime</type>
  <value>2010-04-29 14:03:09Z</value>
</result>

Byte Array:

The value will be Base65 encoded.


<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>bytearray</type>
  <value>SGVsbG8gV29ybGQ=</value>
</result>

null:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <type>null</type>
  <value></value>
</result>

Success/Fail Responses

Error:

<?xml version="1.0" encoding="UTF-8"?>
<error>missing ;</error>

Requests which do not return a value and do not eror normally result with a success response:

<?xml version="1.0" encoding="UTF-8"?>
<success>This can be any message.</success>

Unsupported return type:

<?xml version="1.0" encoding="UTF-8"?>
<unsupportedReturnType>OleDbConnection</unsupportedReturnType>
Privacy Policy | Conditions Of Use

Copyright ©2014 Codecore Technologies, All rights reserved.