{"_id":"5a736918b3aaaa00566629b3","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":31,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255","59f76fef8581dc0010593e6f","5a0c003680a35b0012c35db0","5a8358722e78660075e45f42","5a846645b5ec3a001203517e","5b258091bc7a6700033b9cb5","5b26e48e024807000315a740","5b44edff3306680003663f5c","5b468abd3d4a9e0003789111","5b468d8f3dcb6a0003c6e374","5b47b0b93d4a9e000378a33a","5b538d114ea24f00033c726f","5b6a0efe402b32000336c33f"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"5b47b0b93d4a9e000378a33a","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-07-12T19:49:13.569Z","from_sync":false,"order":12,"slug":"features","title":"Features"},"user":"5a6a26281895510045b2cd40","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-01T19:23:04.828Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"# Overview\n\nProjections 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.\n\n# Details\n\nProjections 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. \n\nProjections 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.\n\n# Operations\n\n* **include**: Provide the values of the listed properties\n\n* **exclude**: Provide the values of all the objects' properties except for those listed\n\n# Examples\n\nSample device `D573bc694ae9ac9419f028b61 ` aliased `stereo`:\n\n```\n{\n    \"id\": \"D573bc694ae9ac9419f028b61\",\n    \"ecosystemId\": \"C573b86eeee43dd7ba0244f8a\",\n    \"environmentId\": \"E573bb9ffd717111220812c3a\",\n    \"type\": \"physical\",\n    \"edgeId\": \"F2-50-BC-59-B9-C2\",\n    \"alias\": \"stereo\"\n    \"meta\": {\n        \"$manufacturer\": \"FancyHome\"\n        \"location\": \"LivingRoom\",\n        \"testEquipment\": false,\n        \"modelYear\": 2017\n        \"volumePresets\":[23, 39, 51, 72, 88]\n    }\n}\n```\n\nSample device `D1a0b4f07228ea674ac07b9bc` aliased `light`:\n\n```\n{\n    \"id\": \"D1a0b4f07228ea674ac07b9bc\",\n    \"ecosystemId\": \"C573b86eeee43dd7ba0244f8a\",\n    \"environmentId\": \"E573bb9ffd717111220812c3a\",\n    \"alias\": \"light\",\n    \"type\": \"physical\",\n    \"meta\": {\n        \"$manufacturer\": \"FancyHome\",\n        \"location\": \"Garage\",\n        \"testEquipment\": true,\n        \"modelYear\": 2016\n        \"successes\": {\n            \"test1\": false,\n            \"test2\": false,\n            \"test3\": true,\n            \"test4\": false\n        },\n        \"colors\": [\"red\", \"white\", \"blue\"]\n        \"brightnessPresets\": [7, 23, 42, 69, 86]\n    }\n}\n```\n\n## Include Example\n\n```\nGET https://ioe.droplit.io/api/devices?environmentId=E573bb9ffd717111220812c3a&projection=include(meta.$manufacturer, meta.successes)\n```\nReturns the JSON object:\n```\n{\n    \"items\": [\n        {\n            \"id\": \"C573b86eeee43dd7ba0244f8a\",\n            \"alias\": \"stereo\",\n            \"meta\": {\n                \"$label\": \"\",\n                \"$manufacturer\": \"FancyHome\"\n            }\n        },\n        {\n            \"id\": \"D1a0b4f07228ea674ac07b9bc\",\n            \"alias\": \"Light\",\n            \"meta\": {\n                \"$label\": \"DevLight\",\n                \"$manufacturer\": \"FancyHome\"\n                \"successes\": {\n                    \"test1\": false,\n                    \"test2\": false,\n                    \"test3\": true,\n                    \"test4\": false\n                },\n            },\n            \"label\": \"DevLight\",\n        }\n    ]\n}\n```\n\n## Exclude Example\n\n```\nGET https://ioe.droplit.io/api/devices?environmentId=E573bb9ffd717111220812c3a&projection=exclude(meta.$manufacturer, meta.successes, meta.$label)\n```\nReturns the JSON object:\n```\n{\n    \"items\": [\n        {\n            \"id\": \"D573bc694ae9ac9419f028b61\",\n            \"ecosystemId\": \"C573b86eeee43dd7ba0244f8a\",\n            \"environmentId\": \"E573bb9ffd717111220812c3a\",\n            \"type\": \"virtual\",\n            \"alias\": \"stereo\",\n            \"meta\": {\n                \"location\": \"LivingRoom\",\n                \"testEquipment\": false,\n                \"modelYear\": 2017,\n                \"volumePresets\": {\n                    \"0\": 23,\n                    \"1\": 39,\n                    \"2\": 51,\n                    \"3\": 72,\n                    \"4\": 88\n                }\n            },\n            \"createdAt\": \"2018-01-11T19:30:42.329Z\"\n        },\n        {\n            \"id\": \"D1a0b4f07228ea674ac07b9bc\",\n            \"ecosystemId\": \"C573b86eeee43dd7ba0244f8a\",\n            \"environmentId\": \"E573bb9ffd717111220812c3a\",\n            \"type\": \"virtual\",\n            \"alias\": \"Light\",\n            \"meta\": {\n                \"location\": \"Garage\",\n                \"testEquipment\": true,\n                \"modelYear\": 2016,\n                \"colors\": {\n                    \"0\": \"red\",\n                    \"1\": \"white\",\n                    \"2\": \"blue\"\n                },\n                \"brightnessPresets\": {\n                    \"0\": 7,\n                    \"1\": 23,\n                    \"2\": 42,\n                    \"3\": 69,\n                    \"4\": 86\n                }\n            },\n            \"createdAt\": \"2018-01-11T19:35:25.614Z\"\n        }\n    ]\n}\n```","excerpt":"Include or exclude particular properties in a response.","slug":"projections","type":"basic","title":"Projections"}

Projections

Include or exclude particular properties in a response.

# 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" } ] } ```