Droplit.io Portal
API Reference

Aliases

Record pseudonyms for developers

Overview

An alias is the human friendly unique ID of a record.

Record IDs 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 contain the characters: a-z, A-Z, 0-9, _
  • No spaces

NOTE: 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.

Uniqueness

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.

Creating an Alias

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.

Using Aliases in the Command Line Tools

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.

droplit device alias D577959875BA712DB9DA477A5 light1
droplit device set light1 BinarySwitch.switch on

Using Aliases in the API

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 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.

PUT https://ioe.droplit.io/v0/api/devices/E571fc182abeca2cc15a134c4;light1/services/BinarySwitch.switch HTTP/1.1
authorization: AUTH_TOKEN

{
	"value": "on"
}

Additionally, aliases and ecosystem domains may be used instead of IDs entirely. If an ecosystem with the domain ecoDomain contains the above environment, now aliased to envAlias, the light within that environment can be accessed in the following manner:

PUT https://ioe.droplit.io/v0/api/devices/ecoDomain;envAlias;light1/services/BinarySwitch.switch HTTP/1.1
authorization: AUTH_TOKEN

{
	"value": "on"
}