WebApi2 Plug-in

Overview

This page will outline the way in which the server was created in order to expose Devices, Scenes, Groups and the Log to clients over HTTP.

Authentication

You must include a valid token with each query to the API. It is very import that you change the allowed X-zvsToken's away from the default in the plugin-manager in zVirtualScenes. This should be done prior to exposing the API to a public facing IP.

Token Header

X-zvsToken: CC2D226814CBC713134BD9D09B892F10A9

jQuery Example

beforeSend: function (xhr) { xhr.setRequestHeader (“X-zvsToken”, “CC2D226814CBC713134BD9D09B892F10A9”); },

Conventions

Content-type should be supplied with each request.

Content-Type: application/json

oData: defines parameters that can be used to modify an OData query. The client sends these parameters in the query string of the request URI. For example, to sort the results, a client uses the $orderby parameter:

http://localhost/odata4/Devices?$orderby=Name

All Supported OData Query Options

Metadata

Clients can use the metadata to discover the type information and relationships for the data set.

Viewing the metadata - GET

/odata4/$metadata

Example output

<edmx:edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" version="4.0">
<edmx:dataservices>
<schema xmlns="http://docs.oasis-open.org/odata/ns/edm" namespace="zvs.DataModel">
<entitytype name="ScheduledTask">
<key>
<propertyref name="Id" />
</key>
<property name="StartTime" type="Edm.DateTimeOffset" nullable="false" />
<property name="Id" type="Edm.Int32" nullable="false" />
<property name="TaskType" type="zvs.DataModel.Tasks.ScheduledTaskType" nullable="false" />
<property name="RepeatIntervalInSeconds" type="Edm.Double" nullable="false" />
<property name="RepeatIntervalInWeeks" type="Edm.Int32" nullable="false" />
<property name="DaysOfWeekToActivate" type="zvs.DataModel.Tasks.DaysOfWeek" nullable="false" />
<property name="RepeatIntervalInMonths" type="Edm.Int32" nullable="false" />
<property name="DaysOfMonthToActivate" type="zvs.DataModel.Tasks.DaysOfMonth" nullable="false" />
<property name="RepeatIntervalInDays" type="Edm.Int32" nullable="false" />
<property name="Name" type="Edm.String" />
<property name="IsEnabled" type="Edm.Boolean" nullable="false" />
<property name="SortOrder" type="Edm.Int32" />
<property name="CommandId" type="Edm.Int32" />
<property name="Argument" type="Edm.String" />
<property name="Argument2" type="Edm.String" />
<property name="TargetObjectName" type="Edm.String" />
<property name="Description" type="Edm.String" />
<navigationproperty name="Command" type="zvs.DataModel.Command" />
</entitytype>
<entitytype name="DeviceValueHistory">...

Query Examples

Find the level of device 3 - GET

/odata4/DeviceValues?$filter=Name eq 'Level' and DeviceId eq 3

Show the first 5 commands - GET

/odata4/Commands?$top=5

Skip the first 100 commands - GET

/odata4/Commands?$skip=100

Find the command to Set Comfort Mode on any OpenZWave Thermostats - GET

/odata4/DeviceTypeCommands?$filter=UniqueIdentifier eq 'SETCONFORTMODE' and DeviceTypeId eq 4

Find the device named Office Light - GET

/odata4/Devices/?$filter=Name eq 'Office Light'

Change name of Scheduled Task with id 1 - PATCH

/odata4/ScheduledTask(1)

Request Body

{
  Name: 'Cool Task'
}

Change name of the Scheduled Task with id of 1 - PATCH

/odata4/ScheduledTask(1)

Request Body

{
  Name: 'Cool Task'
}

Execute Command - POST

/odata4/Commands(2)/Actions.Execute

Request Body

{
    Argument: "50",
    Argument2: ""
}