Queries and Parameters
- Sacha Parisot (Unlicensed)
A query specifies a selection rule for a specified object or objects. A query can be specified within a path element of a URI, or can be added to the end of a URI following a ? character.
- A query specified in a path element is called a path parameter.
- A query specified at the end of a URI following a "?" is called a query parameter.
Query Syntax
A query in IAP/REST is a key-value pair along with an operator that specifies the relationship between the key and the value. The syntax for a query is {key}{operator}{value}. Multiple key-value pairs can be specified, separated by an “&” character as a logical "AND", combining the parameters. The {key}, {operator}, and {value} have the following descriptions:
Key
The key identifies a property of the IAP/REST resources. When included in a path element, the key specifies a property within the IAP/REST object specified by the path element.
Operator
The operator specifies the relation between the key and value. The available operators are:
| Operator | Definition |
|---|---|
| == | Exact match |
| != | Exact mismatch (for a fully specified string) |
| =+ | Regular expression match, case-insensitive |
| !+ | Regular expression mismatch, case-insensitive |
| < | Less than (for numbers and timestamps) |
| <= | Less than or equal (for numbers and timestamps) |
| => | Equal or greater than (for numbers and timestamps) |
| > | Greater than (for numbers and timestamps |
Value
The value specifies the value of the property to be used to identify selected resources. The value can be:
- An absolute value for scalar properties.
- A regular expression for the regular expression match (=+) or regular expression mismatch (!+) operators.
For the regular expression match (=+) and regular expression mismatch (!+) operators, the regular expression syntax is defined as a subset of Perl 5 syntax supported by java.util.regex as described in the java.util.regex documentation at https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.
Regular Expression Encoding
Special characters may need to be encoded before sending the IAP/REST request to the SmartServer. Not all instances of a special character need to be encoded. Encoding depends on where the special character is used in the IAP/REST request.
Device, Block and datapoint names with special characters have to be encoded before sending them to the SmartServer. For example, in the following datapoint XIF path the space in "TeslTest 1", and the "[" and "]" in "nviLamp[1]" have to be encoded.
Datapoint XIF path: TeslaTest 1/device/0/nviLamp[1]
After encoding: TeslaTest%201/device/0/nviLamp%5B1%5D
Regular expressions cannot include characters that are not allowed in URI paths. Any such characters must be percent encoded as described in https://en.wikipedia.org/wiki/Percent-encoding. For example, the following characters that are reserved in RFC 3986 must be encoded as shown below each character:
Following are additional special characters that require percent encoding:
When you add use XIF names in the path parameter you need to add *+xifName== for exact match which is not encoded.
if you want to do additional test criteria for instance names then you need to add *+name= which is not encoded.
Examples
1. This is a simple request for a named datapoint sp within device with Id myDevice: no encoding necessary
GET iap/devs/myDevice/if/Light/0/sp |
2. This addresses all datapoints named sp within any device whose type property matches a regular expression, and whose block type (the profile) is reported as a particular and specific value. All matching blocks are considered regardless of their handle.
GET iap/devs/*+type=+^90000146164[0-4]85/if/*+type==0000000000000000-0/SFPTopenLoopActuator//*/sp |
iap/devs/*+type=+^90000146164[0-4]85/if/*+type==0000000000000000-0/SFPTopenLoopActuator//*/sp
Encoded: "/" = "%2F" in "*+type==0000000000000000-0/SFPTopenLoopActuator/"
GET iap/devs/*+type=+^90000146164[0-4]85/if/*+type==0000000000000000-0%2FSFPTopenLoopActuator%2F/*/sp |
3. To get a datapoint value using XIF names:
Request:
GET /iap/devs/*+name==TeslaTest 1/if/*+xifName==device/0/*+xifName==nviLamp[1]/value |
/iap/devs/*+name==TeslaTest 1/if/*+xifName==device/0/*+xifName==nviLamp[1]/value
Encoded: space = "%20", “[” = “%5B, “]” = “%5D”
GET /iap/devs/*+name==TeslaTest%201/if/*+xifName==device/0/*+xifName==nviLamp%5B1%5D/value |
4. Writing to a datapoint value using XIF names:
Request:
GET /iap/devs/*+name==TeslaTest 1/if/*+xifName==device/0/*+xifName==nviLamp[1]/value |
/iap/devs/*+name==TeslaTest 1/if/*+xifName==device/0/*+xifName==nviLamp[1]/value
Encoded: space in "TeslaTest 1" = "%20", “[” = “%5B, “]” = “%5D”
PUT /iap/devs/*+name==TeslaTest%201/if/device/0/*+xifName==nviLamp%5B0%5D/overrides/17/localization/value |
5. To do a Subscribe GET request for a list of datapoints which is used for IAP/WS:
Request: No encoding needed
PUT /iap/dp/updates/subscribe |
6. To do an On-Demand GET request for a list of datapoints:
Request:
GET /iap/devs/*/if/*/*/*+qualifier=-17qam77/lon/1/device/0/nvoLuxLevel 1,17qam77/lon/3/Lamp/1/nvoLamp[1]/*?max_age=2&noxs=true |
/iap/devs/*/if/*/*/*+qualifier=-17qam77/lon/1/device/0/nvoLuxLevel 1,17qam77/lon/3/Lamp/1/nvoLamp[1]/*?max_age=2&noxs=true
Encoded (qualifier parameter needing encoding): "/"= "%2F", space in "nvoLuxLevel" = "%20", "[" = "%5B, "]" = "%5D"
GET /iap/devs/*/if/*/*/*+qualifier=-17qam77%2Flon%2F1%2Fdevice%2F0%2FnvoLuxLevel%201,17qam77%2Flon%2F3%2FLamp%2F1%2FnvoLamp%5B1%5D/*?max_age=2&noxs=true |