Obtains the present value of a datapoint. The present value conforms to the type specification for the datapoint. You can read/write to one or more datapoints at a time. There are many ways to do a bulk read or bulk writes to multiple datapoints, some of which are listed below.

For reading datapoints you use the same GET request when using REST or REST with WebSockets. When only using REST you will use the GET response data. When using REST with WebSockets you ignore the GET response and just use WebSocket datapoint update. 

For bulk writes, you write the same value to all the datapoints. You will get a HTTP 204 response if there is nothing wrong with the bulk write request. You will get a HTTP 422 if one of the datapoints is already using a higher priority then the one included in the request.

Methods to do bulk read/writes:

1. Use wild cards for parts of in the request URI - take care when writing to multiple datapoints as you may end up writing to an unintended datapoint.
2. Use a list of dpQualifiers to write to specific dataponts (a datapoint dpQualifier is shown in the CMS Datapoint Widget "Show Detail Properties")
3. Use datapoint tags - you will need to add the datapoint tag to the datapoint's tag property prior to using for the datapoint read/write.

URI Definition

Queries

You can include queries with your IAP/REST request to specify a selection rule for your request.  As described in Queries and Parameters, you can specify a query as a  query parameter appended to the end of your URI preceded with a "?" character, or as a path parameter within a path element of the path component.

The optional path parameters for the id, block, block_index, and datapoint_name path elements are listed on the Path Parameters page.

Examples

Get all datapoints named nviValue:

Get all datapoints with a name starting with nvi from devices with normal device health.

Get all datapoints from devices with provisioned status.

An example of a datapoint value Response in JSON format:

Getting datapoint values using dpQualifier list.  A datapoints dpQualifer's is shown in the CMS Datapoint Widget "Show Detail View" or you can programmatically create it.

dpQualifier: <SmartServer SID>/<protocol>/<device DID>/<blockName><blockIndex>/<datapoint XIF name>

Read Request Format:

Example:  dpQualifier List = 17qam88/lon/6/device/0/nviLamp1,17qam88/lon/6/device/0/nviLamp2

Read request (unencoded):

GET     /iap/devs/*/if/*/*/*+qualifier=-17qam88/lon/6/device/0/nviLamp1,17qam88/lon/6/device/0/nviLamp2/value?max_age=2&noxs=true

Get request encoded:

Writing to a datapoint using device name and preset value, without specifying priority (sent at Normal (17) priority).

Writing to a datapoint using device name and preset value, specifying Normal (17) priority.

Writing to a structured datapoint using device name and preset value, without specifying priority (sent at Normal (17) priority).

Writing to a structured datapoint using device name and preset value, specifying Normal (17) priority.

Writing to datapoint using device name and preset value, without specifying priority (sent at Normal (17) priority).

Writing to datapoint using device name and preset value, specifying Normal (17) priority.

Writing the same value to multiple datapoints using dpQualifier list (batch write).  A datapoints dpQualifer's is shown in the CMS Datapoint Widget "Show Detail View" or you can programmatically create it.

dpQualifier: <SmartServer SID>/<protocol>/<device DID>/<blockName><blockIndex>/<datapoint XIF name>

Request Format:

Example: dpQualifier List = 17qam88/lon/6/device/0/nviCount1,17qam88/lon/6/device/0/nviCount2

Write request (unencoded):

PUT     /iap/devs/*/if/*/*/*+qualifier=-17qam88/lon/6/device/0/nviCount1,17qam88/lon/6/device/0/nviCount2/value

Payload: 5

write request encoded:

If nviTemp is 22 degrees C, and the datapoint has localization (CMS Datapoint Property Widget or DLA) to convert it to 71.6 degrees F, but you want to change it to 95 deg F using priority 14.  You can use either one of the following two PUT requests:

• Sending Fahrenheit value: 95

  PUT     /iap/devs/+*name==PulseGen1/if/device/0/nviCount/overrides/14/localization/value          Payload: 95

• Sending Celsius value: 35

  PUT     /iap/devs/+*name==PulseGen1/if/device/0/nviCount/overrides/14/localization/value          Payload: 35