{"_id":"55f2859fec95bb0d00696669","__v":8,"category":{"_id":"55f28172f9f3991900f38a14","version":"55f28172f9f3991900f38a13","__v":2,"project":"54ebb40d6423300d003672c0","pages":["55f28174f9f3991900f38a28","55f2859fec95bb0d00696669"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-23T23:13:18.226Z","from_sync":false,"order":0,"slug":"http-remote-control-api","title":"HTTP Remote Control API"},"user":"5580f88e8625220d00429b74","project":"54ebb40d6423300d003672c0","version":{"_id":"55f28172f9f3991900f38a13","project":"54ebb40d6423300d003672c0","__v":2,"createdAt":"2015-09-11T07:23:30.065Z","releaseDate":"2015-09-11T07:23:30.065Z","categories":["55f28172f9f3991900f38a14","55f28172f9f3991900f38a15","55f28172f9f3991900f38a16","55f66acb297b37170058accb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-11T07:41:19.925Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"All selectors now return a list\"\n}\n[/block]\nPreviously, if you used the `id` or `label` selectors, you would receive a single hash rather than an array. In `v1`, all selectors will now return a list for consistency. In addition. the `label` selector will now match all lights that match the given selector rather than just the \"first\" one.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Multiple selectors in a single request\"\n}\n[/block]\nYou can now combine selectors together with the `,` delimiter. For example, if you want to address a light labelled \"Office\" and a light labelled \"Bedroom\" in the same request, you would use `label:Office,label:Bedroom`. You can combine up to 25 selectors in the one request.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Changes to device listing response\"\n}\n[/block]\n`product_name` and `capabilities` have been moved inside `product`, which breaks apart the name into `name` and `company`. See [List Lights](doc:list-lights) for more details.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Operational responses more consistent\"\n}\n[/block]\nTo ensure consistency, all operation responses now return `207 Multi Status` and rather than a single hash or a list, it is now always a hash in the following format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"results\\\": [\\n  \\t{\\n    \\t\\\"id\\\": \\\"dxxxxxxxxxxxx\\\",\\n      \\\"label\\\": \\\"Light 1\\\",\\n      \\\"status\\\": \\\"ok\\\"\\n    }, // ...\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThis allows future endpoints to return ancillary data without needing client changes.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Deprecated endpoints have been removed\"\n}\n[/block]\nThe following APIs deprecated in v1beta1 have been removed and now return 410 Gone:\n\n* `PUT /lights/[selector]/color` - Use `PUT /lights/[selector]/state` and set the `color` param\n* `PUT /lights/[selector]/power` - Use `PUT /lights/[selector]/state` and set the `power` param rather than `state`\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Validate Color endpoint added\"\n}\n[/block]\nWe've added a [Validate Color](doc:validate-color) endpoint that allows validation of color strings and also returns what the API would interpret the string as.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Improved error checking\"\n}\n[/block]\nIn error responses, `message` has been renamed to `error` to allow for easier checking of errors.\n\nFor example, an error from v1beta1:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"message\\\": \\\"Invalid token\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"v1beta1.json\"\n    }\n  ]\n}\n[/block]\nWill now look like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"Invalid token\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"v1.json\"\n    }\n  ]\n}\n[/block]\nThis allows clients to check for the presence of errors more easily.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"List Scenes API responses improved\"\n}\n[/block]\nThe [List Scenes](doc:list-scenes) API now returns an array of `states` for each `scene`. See [List Scenes](doc:list-scenes) for more details.","excerpt":"","slug":"upgrading-from-v1beta1","type":"basic","title":"Changes since v1beta1"}

Changes since v1beta1


[block:api-header] { "type": "basic", "title": "All selectors now return a list" } [/block] Previously, if you used the `id` or `label` selectors, you would receive a single hash rather than an array. In `v1`, all selectors will now return a list for consistency. In addition. the `label` selector will now match all lights that match the given selector rather than just the "first" one. [block:api-header] { "type": "basic", "title": "Multiple selectors in a single request" } [/block] You can now combine selectors together with the `,` delimiter. For example, if you want to address a light labelled "Office" and a light labelled "Bedroom" in the same request, you would use `label:Office,label:Bedroom`. You can combine up to 25 selectors in the one request. [block:api-header] { "type": "basic", "title": "Changes to device listing response" } [/block] `product_name` and `capabilities` have been moved inside `product`, which breaks apart the name into `name` and `company`. See [List Lights](doc:list-lights) for more details. [block:api-header] { "type": "basic", "title": "Operational responses more consistent" } [/block] To ensure consistency, all operation responses now return `207 Multi Status` and rather than a single hash or a list, it is now always a hash in the following format: [block:code] { "codes": [ { "code": "{\n\t\"results\": [\n \t{\n \t\"id\": \"dxxxxxxxxxxxx\",\n \"label\": \"Light 1\",\n \"status\": \"ok\"\n }, // ...\n ]\n}", "language": "json" } ] } [/block] This allows future endpoints to return ancillary data without needing client changes. [block:api-header] { "type": "basic", "title": "Deprecated endpoints have been removed" } [/block] The following APIs deprecated in v1beta1 have been removed and now return 410 Gone: * `PUT /lights/[selector]/color` - Use `PUT /lights/[selector]/state` and set the `color` param * `PUT /lights/[selector]/power` - Use `PUT /lights/[selector]/state` and set the `power` param rather than `state` [block:api-header] { "type": "basic", "title": "Validate Color endpoint added" } [/block] We've added a [Validate Color](doc:validate-color) endpoint that allows validation of color strings and also returns what the API would interpret the string as. [block:api-header] { "type": "basic", "title": "Improved error checking" } [/block] In error responses, `message` has been renamed to `error` to allow for easier checking of errors. For example, an error from v1beta1: [block:code] { "codes": [ { "code": "{\n \"message\": \"Invalid token\"\n}", "language": "json", "name": "v1beta1.json" } ] } [/block] Will now look like: [block:code] { "codes": [ { "code": "{\n \"error\": \"Invalid token\"\n}", "language": "json", "name": "v1.json" } ] } [/block] This allows clients to check for the presence of errors more easily. [block:api-header] { "type": "basic", "title": "List Scenes API responses improved" } [/block] The [List Scenes](doc:list-scenes) API now returns an array of `states` for each `scene`. See [List Scenes](doc:list-scenes) for more details.