Overview

The Droplit REST API retrieves information about smart devices. Use the following techniques when exploring the API to discover how it works, and how it can be used to control devices.

Versioning

The Droplit API is versioned, and users can specify the version they wish to use by specifying the version in the URL after the domain name. If a version is not specified in the URL, the most current stable version of the API is referenced by default.

Therefore, assuming the most recent version of the Droplit API is v0, the following URLs would be equivalent.

• v0/api/devices
• api/devices

The recommended best practice is to always work with the latest version of the API. Old API versions will be supported for approximately a year after a newer version is created. Before new API versions are released, an email will be sent to developer email addresses, allowing time for application updates where necessary.

Another recommended best practice is to include an “x-api-version” header with the version name in all HTTP requests. This will give the Droplit servers a way to know that an application exists that may not have been updated. If this is the case, Droplit may contact the developer email address to warn that an application will break.

URL Formatting

In REST URLs, names prefixed by a colon (:) are parameters for that URL. For example, in the URL “/api/devices/:id”, the value “id” is a parameter.

Parameters in endpoint URLs are meant to be as descriptive and explicit as possible. By convention, if there is a path parameter that refers to an instance of the main URL resource, it is described as simply as possible, implicitly referring to the resource itself.

For example, in the URL “/devices/:id/tokens/:tokenId”, the “id” parameter refers specifically to a device ID, but that is not explicitly stated. The other parameter, “tokenId”, is explicitly named to show that it is a token ID, since the token is not the primary resource of the endpoint.

Scoped References

An object may be referenced in the API through its parent container. The syntax for doing this is to follow the parent container ID or alias with a semicolon, then the ID or name of the desired object, as PARENT-ID-OR-ALIAS;OBJECT-ID-OR-ALIAS.

This syntax can be used any number of times when referring to an object explicitly. For example, an ecosystem, followed by an environment, followed by a zone, could be prefixed to a device ID. More than one level of scoping, however, is usually much more verbose than necessary.

Any ID or alias parameter may be referenced in this way when making an API call, if desired. There are some instances in the API where this syntax is required, and those instances are explicitly stated for clarity.

Handling Metadata

Metadata is always modified with a PUT endpoint when it is accessed through the REST API. This applies whether metadata is being added, changed, or removed.

Handling Aliases

Aliases are always modified with a PUT endpoint when it is accessed through the REST API. This applies whether metadata is being added, changed, or removed.

The alias must be accessed through its parent container, using a scoped reference. If the parent container itself is using an alias, one can use that alias as well, but that alias must also use a scoped reference.

This example shows an alias “light1” being used to access a binary switch.

PUT https://ioe.droplit.io/api/devices/DEVICE-PARENT-ID;light1/services/BinarySwitch.switch HTTP/1.1
authorization: TOKEN
content-type: application/json

{
	"value": "on"
}

Handling JSON Objects

When JSON objects are modified through the API (for example, a metadata object through a PUT endpoint), the previous object is overwritten. If some information in the previously existing object should be kept, one should retrieve the object with the appropriate GET endpoint, then use that object as a template to add more data, keeping any relevant information intact before adding or changing what is there.