{"_id":"582789abbe5c080f00a5a81e","project":"568bdc1483d2061900d86cdc","parentDoc":null,"__v":0,"category":{"_id":"5845d13063c11b2500379681","__v":0,"version":"582789aabe5c080f00a5a7fe","project":"568bdc1483d2061900d86cdc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-12-05T20:42:24.315Z","from_sync":false,"order":1,"slug":"platform-overview","title":"Platform Overview"},"user":"568bdbc4fe6fcc0d006dc970","version":{"_id":"582789aabe5c080f00a5a7fe","__v":10,"project":"568bdc1483d2061900d86cdc","createdAt":"2016-11-12T21:29:14.915Z","releaseDate":"2016-11-12T21:29:14.915Z","categories":["582789abbe5c080f00a5a7ff","582789abbe5c080f00a5a800","582789abbe5c080f00a5a801","582789abbe5c080f00a5a802","582789abbe5c080f00a5a803","582789abbe5c080f00a5a804","582789abbe5c080f00a5a805","582789abbe5c080f00a5a806","582789abbe5c080f00a5a807","582789abbe5c080f00a5a808","5827ea984ca29e0f00137a9e","583df597887db62f00644283","583df5d9c622791900e78da5","5845cd8763c11b250037967d","5845d13063c11b2500379681","5859e859e3306d1900126725","587aeb9a01cf3a0f008359eb","587c422af45e2d0f005e200d","587d84dc82f6f30f004ceee5"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta2","version_clean":"0.0.0","version":"0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-13T23:07:29.854Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Introduction\"\n}\n[/block]\n**Alias** is the human-friendly unique Id of a record.\n\nRecord Id’s are long and cumbersome to read and communicate. They also look similar and are difficult to differentiate in the context of a set of items.\n\nAn _alias_ is a pseudonym that can be applied to any device, zone, or environment.\n\nAliases allow you to easily refer to items in your ecosystem when using the command line tools or API.\n\nAliases must meet the following requirements:\n - Between 1 and 24 characters\n - Only the contain characters: `a-z`, `A-Z`, `0-9`, `_`\n - No spaces\n - Aliases are case-sensitive\n\nYou may see aliases represented throughout the system prefixed by an `:::at:::` symbol. So a device with an alias of `thing1` may be described as `@thing1`.\n\nThe `@` prefix is optional for all current uses, but may become required in some future features.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Uniqueness\"\n}\n[/block]\nAliases are required to be unique within the scope of the parent container.\n\nFor device and zone, the alias is unique within the parent environment.\n\nFor environments, the alias is unique within the parent ecosystem.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating an Alias\"\n}\n[/block]\nAn alias can be applied to any record that supports aliases simply by setting its `alias` property using the record's `PUT` update method.\n\nAn alias can be removed by setting the `alias` property to `null` with a `PUT` operation.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Aliases in the Command Line tools\"\n}\n[/block]\nAnywhere an ID could be specified for a Device, Zone, or Environment, an alias can be substituted.\n\nThe `alias` command sets the alias for any supported record.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"droplit device alias D577959875BA712DB9DA477A5 light1\\ndroplit device set light1 BinarySwitch.switch on\",\n      \"language\": \"text\",\n      \"name\": \"console\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Aliases in the API\"\n}\n[/block]\nAliases can be used in place of the `id` in API calls. Because aliases are only unique within their parent scope, the parent scope must be specified when using aliases in in API calls.\n\nTo do this, specify the parent `id` separated from the alias with a semicolon `;`.\n\n`ENVIRONMENT_ID;DEVICE_ALIAS`\n\nFor example: A device in Environment `E53c19b2f3008801c0f4c3dca` with alias `light1` could be substituted for the Id with the following format:\n\n`E53c19b2f3008801c0f4c3dca;light1`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PUT https://ioe.droplit.io/v0/api/devices/E571fc182abeca2cc15a134c4;light1/services/BinarySwitch.switch HTTP/1.1\\nauthorization: AUTH_TOKEN\\n\\n{\\n\\t\\\"value\\\": \\\"on\\\"\\n}\",\n      \"language\": \"http\",\n      \"name\": \"HTTP\"\n    }\n  ]\n}\n[/block]","excerpt":"Record pseudonyms for developers","slug":"aliases","type":"basic","title":"Aliases"}

Aliases

Record pseudonyms for developers

[block:api-header] { "type": "basic", "title": "Introduction" } [/block] **Alias** is the human-friendly unique Id of a record. Record Id’s are long and cumbersome to read and communicate. They also look similar and are difficult to differentiate in the context of a set of items. An _alias_ is a pseudonym that can be applied to any device, zone, or environment. Aliases allow you to easily refer to items in your ecosystem when using the command line tools or API. Aliases must meet the following requirements: - Between 1 and 24 characters - Only the contain characters: `a-z`, `A-Z`, `0-9`, `_` - No spaces - Aliases are case-sensitive You may see aliases represented throughout the system prefixed by an `@` symbol. So a device with an alias of `thing1` may be described as `@thing1`. The `@` prefix is optional for all current uses, but may become required in some future features. [block:api-header] { "type": "basic", "title": "Uniqueness" } [/block] Aliases are required to be unique within the scope of the parent container. For device and zone, the alias is unique within the parent environment. For environments, the alias is unique within the parent ecosystem. [block:api-header] { "type": "basic", "title": "Creating an Alias" } [/block] An alias can be applied to any record that supports aliases simply by setting its `alias` property using the record's `PUT` update method. An alias can be removed by setting the `alias` property to `null` with a `PUT` operation. [block:api-header] { "type": "basic", "title": "Using Aliases in the Command Line tools" } [/block] Anywhere an ID could be specified for a Device, Zone, or Environment, an alias can be substituted. The `alias` command sets the alias for any supported record. [block:code] { "codes": [ { "code": "droplit device alias D577959875BA712DB9DA477A5 light1\ndroplit device set light1 BinarySwitch.switch on", "language": "text", "name": "console" } ] } [/block] [block:api-header] { "type": "basic", "title": "Using Aliases in the API" } [/block] Aliases can be used in place of the `id` in API calls. Because aliases are only unique within their parent scope, the parent scope must be specified when using aliases in in API calls. To do this, specify the parent `id` separated from the alias with a semicolon `;`. `ENVIRONMENT_ID;DEVICE_ALIAS` For example: A device in Environment `E53c19b2f3008801c0f4c3dca` with alias `light1` could be substituted for the Id with the following format: `E53c19b2f3008801c0f4c3dca;light1`. [block:code] { "codes": [ { "code": "PUT https://ioe.droplit.io/v0/api/devices/E571fc182abeca2cc15a134c4;light1/services/BinarySwitch.switch HTTP/1.1\nauthorization: AUTH_TOKEN\n\n{\n\t\"value\": \"on\"\n}", "language": "http", "name": "HTTP" } ] } [/block]