Overview

Filters are used to list resources that meet a specified criteria. If only one
property of a resource is required, then instead of receiving all the devices in
an environment and manually throwing away the undesired ones, a filter can be
applied that will only provide the requested property.

Details

Filters are applied to properties, such as meta.$manufacturer, to discriminate
against the values of the properties. They are applied as a query parameter to the
environment, device, zone, and user endpoints. Since they are a query parameter,
invalid URL characters must be escaped.

Filters are supported on every property, except id, for the list devices, list environments, and list zones endpoints.

Operations

• not: Negate the value of the passed expression

Check if:

• exists: the property exists

• nexists: the property does not exist

• eq: the two given values are equivalent

• neq: the two given values are different

Return true if:

• and: all the operations are true

• or: at least one value is true

• nor: no values are true

• contains: the values are elements of the passed list

• ncontains: the values are not elements of the passed list

• in: the property is one of the listed values

• nin: the property is not among the list of passed values

• lt: the first value is less than the second value

• lte: the first value is less than or equal to the second value

• gt: the first value is greater than the second value

• gte: the first value is greater than or equal to the second value

Operation Arguments

• property: array of values

• value: element of a property

• operation: action that returns a boolean value (not, in, contains, etc.)

Formats

Negation:

not

?filter=not(operation)

Logical Comparators:

lt, lte, gt, gte, eq, neq

?filter=comparator(property, value)

Logical Operators:

and, or, nor

?filter=operator(operation, operation)

Array Operators:

contains, ncontains

?filter=operator(property, value)

Existence Operators:

exists, nexists

?filter=operator(property)

Matching Operators:

in, nin

?filter=operator(property, value, value, ...)

Examples

Sample device C5aw24f04teb96bfc12o6e2cb aliased stereo:

{
    "id": "C5aw24f04teb96bfc12o6e2cb",
    "ecosystemId": "C5qebkf2627ab6vf4u2e39d2w",
    "environmentId": "E5k0j450a9m99y00c128te2cv",
    "type": "physical",
    "edgeId": "F2-50-BC-59-B9-C2",
    "alias": "stereo",
    "meta": {
        "$manufacturer": "FancyHome",
        "location": "LivingRoom",
        "testEquipment": false,
        "modelYear": 2017,
        "volumePresets": [23, 39, 51, 72, 88]
    }
}

Sample device D1a0b4f07228ea674ac07b9bc aliased light:

{
    "id": "D1a0b4f07228ea674ac07b9bc",
    "ecosystemId": "C52eb9f2627ab6af412e39d27",
    "environment": "E5901450a9e99f00c128be2c1",
    "alias": "light",
    "type": "physical",
    "meta": {
        "$manufacturer": "FancyHome",
        "location": "Garage",
        "testEquipment": true,
        "modelYear": 2016,
        "successes": {
            "test1": false,
            "test2": false,
            "test3": true,
            "test4": false
        },
        "colors": ["red", "white", "blue"],
        "brightnessPresets": [7, 23, 42, 69, 86]
    }
}

Logical Comparison:

?filter=lte(meta.testEquipment, false)

Returns stereo

?filter=gte(meta.modelYear, 2016), eq(type, "physical")

Returns stereo and light

📘

NOTE

Each applied filter is assumed to be required.

Logical Operations:

?filter=nor(eq(meta.$manufacturer, "FancyFake"), lt(meta.modelYear, 2016))

Returns true

?filter=or(eq(meta[successes][test3], false), gt(meta.modelYear, 2017))

Returns false

Array Operations:

?filter=contains(meta.brightnessPresets, 42)

Returns true

?filter=ncontains(meta.colors, "white")

Returns false

Existence Operations:

?filter=exists(meta.successes)

Returns light.json

?filter=nexists(meta.modelYear)

Returns {}

Matching Operations:

?filter=in(meta.location, "LivingRoom", "BedRoom")

Returns stereo

?filter=nin(meta.location, "LivingRoom", "DiningRoom"), contains(meta.colors, "red")

Returns light