{"_id":"59a735323fe4d90025117edf","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":19,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"59a734eb757d030019b85af8","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-08-30T21:58:03.883Z","from_sync":false,"order":6,"slug":"rest-api-usage","title":"REST API Usage"},"user":"58cc41f21751ce2f003be3b7","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-30T21:59:14.372Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"# Overview\n\nThe 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.\n\n# Versioning\n\nThe 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.\n\nTherefore, assuming the most recent version of the Droplit API is v0, the following URLs would be equivalent.\n* v0/api/devices\n* api/devices\n\nThe 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.\n\nAnother 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.\n\n# URL Formatting\n\nIn 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.\n\nParameters 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.\n\nFor 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.\n\n# Scoped References\n\nAn 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`.\n\nThis 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.\n\nAny 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.\n\n# Handling Metadata\n\nMetadata 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.\n\n# Handling Aliases\n\nAliases 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.\n\nThe 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.\n\nThis example shows an alias “light1” being used to access a binary switch.\n```\nPUT https://ioe.droplit.io/api/devices/DEVICE-PARENT-ID;light1/services/BinarySwitch.switch HTTP/1.1\nauthorization: TOKEN\ncontent-type: application/json\n{\n\t\"value\": \"on\"\n}\n```\n\n# Handling JSON Objects\n\nWhen 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.","excerpt":"","slug":"rest-api-usage-techniques","type":"basic","title":"Usage Techniques"}
# 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.