Overview

Projections are used to get specific properties on each record from a list. Instead of receiving every property for each device and manually extracting the desired information, add a projection to return only the needed properties on each record.

Details

Projections are applied to properties, such as meta.$manufacturer, in order to either include or exclude them in the results. The values of id, alias, and meta.$label are returned by default when making an include query, but all properties other than id can be excluded.

Projections are applied as a query parameter on the environment, device, zone, and user endpoints. Since they are a query parameter, invalid URL characters must be escaped.

Operations

• include: Provide the values of the listed properties

• exclude: Provide the values of all the objects' properties except for those listed

Examples

Sample device D573bc694ae9ac9419f028b61 aliased stereo:

{
    "id": "D573bc694ae9ac9419f028b61",
    "ecosystemId": "C573b86eeee43dd7ba0244f8a",
    "environmentId": "E573bb9ffd717111220812c3a",
    "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": "C573b86eeee43dd7ba0244f8a",
    "environmentId": "E573bb9ffd717111220812c3a",
    "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]
    }
}

Include Example

GET https://ioe.droplit.io/api/devices?environmentId=E573bb9ffd717111220812c3a&projection=include(meta.$manufacturer, meta.successes)

Returns the JSON object:

{
    "items": [
        {
            "id": "C573b86eeee43dd7ba0244f8a",
            "alias": "stereo",
            "meta": {
                "$label": "",
                "$manufacturer": "FancyHome"
            }
        },
        {
            "id": "D1a0b4f07228ea674ac07b9bc",
            "alias": "Light",
            "meta": {
                "$label": "DevLight",
                "$manufacturer": "FancyHome"
                "successes": {
                    "test1": false,
                    "test2": false,
                    "test3": true,
                    "test4": false
                },
            },
            "label": "DevLight",
        }
    ]
}

Exclude Example

GET https://ioe.droplit.io/api/devices?environmentId=E573bb9ffd717111220812c3a&projection=exclude(meta.$manufacturer, meta.successes, meta.$label)

Returns the JSON object:

{
    "items": [
        {
            "id": "D573bc694ae9ac9419f028b61",
            "ecosystemId": "C573b86eeee43dd7ba0244f8a",
            "environmentId": "E573bb9ffd717111220812c3a",
            "type": "virtual",
            "alias": "stereo",
            "meta": {
                "location": "LivingRoom",
                "testEquipment": false,
                "modelYear": 2017,
                "volumePresets": {
                    "0": 23,
                    "1": 39,
                    "2": 51,
                    "3": 72,
                    "4": 88
                }
            },
            "createdAt": "2018-01-11T19:30:42.329Z"
        },
        {
            "id": "D1a0b4f07228ea674ac07b9bc",
            "ecosystemId": "C573b86eeee43dd7ba0244f8a",
            "environmentId": "E573bb9ffd717111220812c3a",
            "type": "virtual",
            "alias": "Light",
            "meta": {
                "location": "Garage",
                "testEquipment": true,
                "modelYear": 2016,
                "colors": {
                    "0": "red",
                    "1": "white",
                    "2": "blue"
                },
                "brightnessPresets": {
                    "0": 7,
                    "1": 23,
                    "2": 42,
                    "3": 69,
                    "4": 86
                }
            },
            "createdAt": "2018-01-11T19:35:25.614Z"
        }
    ]
}