Permalink
Fetching contributors…
Cannot retrieve contributors at this time
1581 lines (1381 sloc) 44.6 KB
<br><br>
<p>
The device API defines a set of services to create, monitor, control and
activate any devices.
</p>
<hr>
<h2 id="get-a-device">GET /devices/:id</h2>
<p>Returns extended information for a given device identified from its ID.</p>
<h3>Resource URL</h3>
<div class="code-block">
<pre><code>GET https://api.lelylan.com/devices/:id</code></pre>
</div>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td class="parameter">
<span>id</span>
<span class="info">required</span>
</td>
<td>
The ID of the desired device.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#get-a-device-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#get-a-device-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#get-a-device-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#get-a-device-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#get-a-device-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="get-a-device-curl">
<div class="preview">
<pre><xmp>curl https://api.lelylan.com/devices/<id> \
-H 'Authorization: Bearer <token>'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
Lelylan.Device.find('<id>', callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
Device.find('<id>').success(function(response) { $scope.device = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
device = lelylan.device('<id>')</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
from lelylan import devices
device = devices.get_dev('<id>')</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<div class="code-block"><pre><code>HTTP/1.1 200 OK</code></pre></div>
<h3 id="device-representation">Example body response</h3>
<div class="code-block"><pre><code>{
"uri": "https://api.lelylan.com/devices/5042344b95fc441000000001",
"id": "5042344b95fc441000000001",
"name": "Light",
"type": {
"id": "5042310470eda60a0000000d",
"uri": "https://api.lelylan.com/types/5042310470eda60a0000000d"
},
"categories": ["lights"],
"physical": { "uri": "https://arduino.house.com/5042205c70eda61" },
"pending": false,
"properties": [{
"uri": "https://api.lelylan.com/properties/518be5a700045e1521000001",
"id": "518be5a700045e1521000001",
"value": "off",
"expected": "off",
"pending": false,
"accepted": [
{ "key": "on", "value": "On" },
{ "key": "off", "value": "Off" }
]
}, {
"uri": "https://api.lelylan.com/properties/50420c3a267ff51300000001",
"id": "50420c3a267ff51300000001",
"value": "100",
"expected": "100",
"pending": false,
"accepted": []
}],
"owner": {
"id": "5036227a4f1b030200000001",
"uri": "https://api.lelylan.com/people/5036227a4f1b030200000001"
},
"maker": {
"id": "5036227a4f1b030200000001",
"uri": "https://api.lelylan.com/people/5036227a4f1b030200000001"
},
"activated": true,
"created_at": "2013-05-13T14:22:11Z",
"updated_at": "2013-05-13T16:41:57Z",
"updated_from": "Alice"
}</code></pre></div>
<h3>Body Response explained</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td>uri</td>
<td>Device URI.</td>
</tr>
<tr>
<td>id</td>
<td>Device ID.</td>
</tr>
<tr>
<td>name</td>
<td>Device name.</td>
</tr>
<tr>
<td>type</td>
<td>Device typeID and URI.</td>
</tr>
<tr>
<td>physical</td>
<td>Connected physical device URI.</td>
</tr>
<tr>
<td>owner</td>
<td>Device owner having full control on the device.</td>
</tr>
<tr>
<td>maker</td>
<td>Device creator.</td>
</tr>
<tr>
<td>activated</td>
<td>Device activation status<./td>
</tr>
<tr>
<td>categories</td>
<td>Device categories.</td>
</tr>
<tr>
<td>properties</td>
<td>Device properties.</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.uri.</span>
</td>
<td>Property URI</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.id.</span>
</td>
<td>Property ID</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.value</span>
</td>
<td>
Property value.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.expected</span>
</td>
<td>
Expected property value.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.pending</span>
</td>
<td>
Property pending status.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.accepted</span>
</td>
<td>
List of accepted values.
<a href="/support#faq-accepted-values">Learn more about</a>.
</td>
</tr>
</tbody>
</table>
<hr>
<h2 id="get-a-device-private-info">GET /devices/:id/privates</h2>
<p>
Returns private information for a given device identified from its ID.
</p>
<div class="alert alert-info">
<p>
<span class="label label-lelylan">notice</span>
To access this service you must use the <a href="/api#oauth-scopes">privates</a> scope.
</p>
</div>
<h3>Resource URL</h3>
<div class="code-block">
<pre><code>GET https://api.lelylan.com/devices/:id/privates</code></pre>
</div>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td class="parameter">
<span>id</span>
<span class="info">required</span>
</td>
<td>
The ID of the desired device.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#get-a-device-private-info-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#get-a-device-private-info-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#get-a-device-private-info-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#get-a-device-private-info-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#get-a-device-private-info-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="get-a-device-private-info-curl">
<div class="preview">
<pre><xmp>curl https://api.lelylan.com/devices/<id>/privates \
-H 'Authorization: Bearer <token>'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-private-info-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
Lelylan.Device.privates('<id>', callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-private-info-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
Device.privates('<id>').success(function(response) { $scope.device = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-private-info-ruby">
<div class="pre class="prettyprint"view">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
device = lelylan.device_privates('<id>');</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-a-device-private-info-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
from lelylan import devices
device = devices.get_dev_privates('<id>')</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<div class="code-block"><pre><code>HTTP/1.1 200 OK</code></pre></div>
<h3 id="device-representation">Example body response</h3>
<div class="code-block"><pre><code>{
"uri": "https://api.lelylan.com/devices/5042344b95fc441000000001",
"id": "5042344b95fc441000000001",
"name": "Closet dimmer",
"secret": "fkJVeURdtONfXw40wB+K0xI2Zxxxxxxxx",
"activation_code": "3a9e8732e30c7c06031ad28fd5310425xxxxxxxx",
}</code></pre></div>
<h3>Body Response explained</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td>uri</td>
<td>Device URI.</td>
</tr>
<tr>
<td>id</td>
<td>Device ID.</td>
</tr>
<tr>
<td>name</td>
<td>Device name.</td>
</tr>
<tr>
<td>secret</td>
<td>Unique device secret used to secure the communication with the physical world.</td>
</tr>
<tr>
<td>activation_code</td>
<td>Device activation code used to claim the device ownership.</td>
</tr>
</tbody>
</table>
<hr>
<h2 id="get-all-devices">GET /devices</h2>
<p>Returns a list of owned devices.</p>
<h3>Resource URL</h3>
<pre><code>GET https://api.lelylan.com/devices</code></pre>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td class="parameter">
<span>name</span>
<span class="info">optional</span>
</td>
<td>
Device name to search.
</td>
</tr>
<tr>
<td class="parameter">
<span>type</span>
<span class="info">optional</span>
</td>
<td>
Type ID to search.
</td>
</tr>
<tr>
<td class="parameter">
<span>physical</span>
<span class="info">optional</span>
</td>
<td>
Physical device URI to search.
</td>
</tr>
<tr>
<td class="parameter">
<span>properties[id]</span>
<span class="info">optional</span>
</td>
<td>
Property ID to search.
</td>
</tr>
<tr>
<td class="parameter">
<span>properties[value]</span>
<span class="info">optional</span>
</td>
<td>
Property value to search.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="parameter">
<span>properties[expected]</span>
<span class="info">optional</span>
</td>
<td>
Expected value to search.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="parameter">
<span>properties[pending]</span>
<span class="info">optional</span>
</td>
<td>
Pending property status to search.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
<span class="info">Valid values: true, false.</span>
</td>
</tr>
<tr>
<td class="parameter">
<span>start</span>
<span class="info">optional</span>
</td>
<td>
ID of the last fetched record.
Learn more about <a href="/api#core-concepts-infinite-scrolling-pagination">pagination</a>.
</td>
</tr>
<tr>
<td class="parameter">
<span>per</span>
<span class="info">optional</span>
<span class="info">default to '25'</span>
</td>
<td>
Number of resources per page.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#get-all-devices-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#get-all-devices-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#get-all-devices-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#get-all-devices-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#get-all-devices-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="get-all-devices-curl">
<div class="preview">
<pre><xmp>curl https://api.lelylan.com/devices?name=light \
-H 'Authorization: Bearer <token>'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-all-devices-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
Lelylan.Device.all({ 'name': 'light' }, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-all-devices-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">
<div ng-repeat="device in devices">{{device}}</div>
</div>
<script>
function LelylanController($scope, Device) {
Device.all({ name: 'light' }).success(function(response) { $scope.devices = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-all-devices-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
devices = lelylan.devices(name: 'light')</xmp></pre>
</div>
</div>
<div class="tab-pane" id="get-all-devices-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
from lelylan import devices
devices = devices.get_all_dev({ name: 'light' })</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<div class="code-block"><pre><code>HTTP/1.1 200 OK</code></pre></div>
<h3>Example body response</h3>
<div class="code-block"><pre><code>[
{ # device representation },
{ # device representation },
...
]</code></pre></div>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<hr>
<h2 id="create-a-device">POST /devices</h2>
<p>
Create a device and returns extended information for it.
</p>
<h3>Resource URL</h3>
<pre><code>POST https://api.lelylan.com/devices</code></pre>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td class="parameter">
<span>name</span>
<span class="info">required</span>
</td>
<td>
Device name.
</td>
</tr>
<tr>
<td class="parameter">
<span>type.id</span>
<span class="info">required</span>
</td>
<td>
Type ID (check out <a href="http://lelylan.github.io/types-dashboard-ng/#/">available types</a> or
create a new one).
</td>
</tr>
<tr>
<td class="parameter">
<span>physical.uri</span>
<span class="info">optional</span>
</td>
<td>
Physical device URI. <a href="/api#api-physical">Learn more about</a>.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#create-a-device-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#create-a-device-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#create-a-device-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#create-a-device-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#create-a-device-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="create-a-device-curl">
<div class="preview">
<pre><xmp>curl -X POST https://api.lelylan.com/devices \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Closet dimmer",
"type": { "id": "<id>" },
"physical": { "uri": "<physical-device-uri>" }
}'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="create-a-device-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
var params = {
name: 'Closet dimmer',
type: { id: '<id>' },
physical: { uri: '<physical-device-uri>' } };
device = Lelylan.Device.create(params, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="create-a-device-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
var params = {
name: 'Closet dimmer',
type: { id: '<id>' },
physical: { uri: '<physical-device-uri>' } };
Device.create(params).success(function(response) { $scope.device = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="create-a-device-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
params = {
name: 'Closet dimmer',
type: { id: '<id>' },
physical: { uri: '<physical-device-uri>' } };
device = lelylan.create_device(params)</xmp></pre>
</div>
</div>
<div class="tab-pane" id="create-a-device-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = {
name: 'Closet dimmer',
type: { id: '<id>' },
physical: { uri: '<physical-device-uri>' } };
from lelylan import devices
device = devices.create_dev(params)</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<div class="code-block"><pre><code>HTTP/1.1 201 Created
Location: https://api.lelylan.com/devices/5042344b95fc441000000001</code></pre></div>
<h3>Example body response</h3>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<hr>
<h2 id="update-a-device">PUT /devices/:id</h2>
<p>
Update a device identified from its ID and returns extended information for it.
</p>
<div class="alert alert-info">
<p>
<span class="label label-lelylan">notice</span>
The device type can't be updated.
</p>
</div>
<h3>Resource URL</h3>
<pre><code>PUT https://api.lelylan.com/devices/:id</code></pre>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td>
<span>id</span>
<span class="info">required</span>
</td>
<td>
The ID of the desired device.
</td>
</tr>
<tr>
<td>
<span>name</span>
<span class="info">optional</span>
</td>
<td>
Device name.
</td>
</tr>
<tr>
<td>
<span>physical.uri</span>
<span class="info">optional</span>
</td>
<td>
Physical device URI. <a href="/api#api-physical">Learn more about</a>
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#update-a-device-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#update-a-device-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#update-a-device-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#update-a-device-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#update-a-device-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="update-a-device-curl">
<div class="preview"><pre><xmp>curl -X PUT https://api.lelylan.com/devices/<id> \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{ "name": "Zigbee closet dimmer" }'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-a-device-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
var params = { name: 'Zigbee closet dimmer' };
Lelylan.Device.update('<id>', params, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-a-device-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
var params = { name: 'Zigbee closet dimmer' };
Device.update('<id>', params).success(function(response) { $scope.device = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-a-device-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
params = { name: 'Zigbee closet dimmer' }
device = lelylan.update_device('<id>', params)</xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-a-device-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = { name: 'Zigbee closet dimmer' }
from lelylan import devices
device = devices.update_dev('<id>', params)</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<div class="code-block"><pre><code>HTTP/1.1 200 OK</code></pre></div>
<h3>Example body response</h3>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<hr>
<h2 id="update-device-properties">PUT /devices/:id/properties</h2>
<p>
Update properties on a device identified from its ID and returns extended
representation for it. If a physical device is connected, Lelylan forward the
changes to the physical world.
</p>
<h3>Resource URL</h3>
<pre><code>PUT https://api.lelylan.com/devices/:id/properties</code></pre>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td>
<span>id</span>
<span class="info">required</span>
</td>
<td>
The ID of the desired device.
</td>
</tr>
<tr>
<td class="parameter">
<span>properties</span>
<span class="info">required</span>
</td>
<td>
Array of properties to change.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.id</span>
<span class="info">required</span>
</td>
<td>
Property ID.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.value</span>
<span class="info">optional</span>
</td>
<td>
Property value.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.expected</span>
<span class="info">optional</span>
</td>
<td>
Expected property value.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.pending</span>
<span class="info">optional</span>
</td>
<td>
Property pending status.
<a href="/support#faq-value-expected-pending">Learn more about</a>.
<span class="info">Valid values: true, false.</span>
</td>
</tr>
<tr>
<td class="nested">
<span>&raquo; property.accepted</span>
<span class="info">optional</span>
</td>
<td>
List of accepted values.
<a href="/support#faq-accepted-values">Learn more about</a>.
<span class="info">Valid values: JSON objects.</span>
</td>
</tr>
</tbody>
</table>
<h3>Example Requests</h3>
<p>Set the device <code>status</code> to <code>on</code> and the device <code>intensity</code> to <code>50%</code>.</p>
<ul class="nav nav-tabs">
<li class="active"><a href="#update-properties-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#update-properties-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#update-properties-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#update-properties-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#update-properties-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="update-properties-curl">
<div class="preview"><pre><xmp>curl -X PUT https://api.lelylan.com/devices/<id>/properties \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"properties": [{
"id": "<status>",
"value": "on"
},{
"id": "<intensity>",
"value": "50" }
]
}'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-properties-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
var params = {
properties:
[ { id: '<status>',
value: 'on' },
{ id: '<intensity>',
value: '50' } ] };
Lelylan.Device.properties('<id>', params, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-properties-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
var params = {
properties:
[ { id: '<status>', value: 'on' },
{ id: '<intensity>', value: '50' } ] };
Device.properties('<id>', params).success(function(response) { $scope.device = response });
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-properties-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
params = {
properties:
[ { id: '<status>',
value: 'on' },
{ id: '<intensity>',
value: '50' } ] }
device = lelylan.device_properties('<id>', params)</xmp></pre>
</div>
</div>
<div class="tab-pane" id="update-properties-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = {
properties:
[ { id: '<status>',
value: 'on' },
{ id: '<intensity>',
value: '50' } ] }
from lelylan import devices
device = devices.update_dev_prop('<id>', params)</xmp></pre>
</div>
</div>
</div>
<h3>Example body response</h3>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<hr>
<h2 id="delete-a-device">DELETE /devices/:id</h2>
<p>
Delete a device identified from its ID and return extended information for it.
</p>
<h3>Resource URL</h3>
<pre><code>DELETE https://api.lelylan.com/devices/:id</code></pre>
<h3>Parameters</h3>
<table class="zebra-striped">
<tbody>
<tr>
<td class="parameter">
<span>id</span>
<span class="info">required</span>
</td>
<td>
The ID of the desired device.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#delete-a-device-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#delete-a-device-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#delete-a-device-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#delete-a-device-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#delete-a-device-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="delete-a-device-curl">
<div class="preview"><pre><xmp>curl -X DELETE https://api.lelylan.com/devices/<id> \
-H 'Authorization: Bearer <token>'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="delete-a-device-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
Lelylan.Device.delete('<id>', callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="delete-a-device-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
Device.delete('<id>').success(function(response) { $scope.device = response })
};
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="delete-a-device-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
device = lelylan.delete_device('<id>')</xmp></pre>
</div>
</div>
<div class="tab-pane" id="delete-a-device-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
from lelylan import devices
device = devices.delete_dev('<id>')</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<pre><code>HTTP/1.1 200 OK</code></pre>
<h3>Example body response</h3>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<% if false %>
<!-- we need to fix this service functionality before using it -->
<hr>
<h2 id="">PUT /devices/:id/functions</h2>
<p>
Execute a function on a device identified from its ID and returns extended representation
for it. If a physical device is connected, Lelylan forward the changes to the
<a href="/api/physicals">physical world</a>.
</p>
<h3>Resource URL</h3>
<div class="preview">
<pre><code>PUT https://api.lelylan.com/devices/:id/functions</code></pre>
</div>
<h3>Parameters</h3>
<table class="zebra-striped">
<tbody>
<tr>
<td class="parameter">
<span>id</span>
<span class="info">required</span>
</td>
<td>
The ID of the desired device.
</td>
</tr>
<tr>
<td class="parameter">
<span>function</span>
<span class="info">required</span>
</td>
<td>
Function ID to execute.
</td>
</tr>
<tr>
<td class="parameter">
<span>properties</span>
<span class="info">optional</span>
</td>
<td>
Array of properties.
</td>
</tr>
<tr>
<td class="parameter nested">
<span>&raquo; property.id</span>
<span class="info">required</span>
</td>
<td>
Property ID.
</td>
</tr>
<tr>
<td class="parameter nested">
<span>&raquo; property.value</span>
<span class="info">optional</span>
</td>
<td>
Property value.
</td>
</tr>
<tr>
<td class="parameter nested">
<span>&raquo; property.expected</span>
<span class="info">optional</span>
</td>
<td>
Expected property value. <a href="/community/faq#value-expected-pending">Learn more about</a>
</td>
</tr>
<tr>
<td class="parameter nested">
<span>&raquo; property.pending</span>
<span class="info">optional</span>
</td>
<td>
Property pending status. <a href="/community/faq#value-expected-pending">Learn more about</a>
<span class="info">Valid values: true, false.</span>
</td>
</tr>
</tbody>
</table>
<h3>Example Requests</h3>
<p>
<strong>Turn on a device</strong>. In this example we do not send properties because the function
<code>turns on</code> set the property <code>status</code> to <code>on</code> by default.
</p>
<ul class="nav nav-tabs">
<li class="active"><a href="#execute-a-function-i-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#execute-a-function-i-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#execute-a-function-i-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#execute-a-function-i-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#execute-a-function-i-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="execute-a-function-i-curl">
<div class="preview"><pre><xmp>curl -X PUT https://api.lelylan.com/devices/<id>/functions \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{ "function": "https://api.lelylan.com/functions/<turn-on>" }'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-i-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
var params = { function: '<turn-on>' };
Lelylan.Device.execute('<id>', params, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-i-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
var params = { function: '<turn-on>' };
$scope.device = new Device({ id: '<id>', function: params.function});
$scope.device.$execute();
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-i-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
params = { function: '<turn-on>' }
device = lelylan.execute('<id>', params)</xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-i-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = { function: '<turn-on>' }
from lelylan import devices
device = devices.exec_dev_func('<id>', params)</xmp></pre>
</div>
</div>
</div>
<p>
<strong>Set the device intensity to 90%</strong>. In this example the function sets the
property <code>status</code> to <code>on</code> by default and expects the intensity value
to be sent from the user.
</p>
<ul class="nav nav-tabs">
<li class="active"><a href="#execute-a-function-ii-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#execute-a-function-ii-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#execute-a-function-ii-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#execute-a-function-ii-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#execute-a-function-ii-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="execute-a-function-ii-curl">
<div class="preview">
<pre><xmp>curl -X PUT https://api.lelylan.com/devices/<id>/functions \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"function": "<set-intensity>"
"properties": [{
"id": "<intensity>",
"value": "90" }
]
}'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-ii-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
var params = {
function: '<set-intensity>',
properties:
[ { id: '<intensity>',
value: '90' } ] };
Lelylan.Device.execute('<id>', params, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-ii-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{device}}</div>
<script>
function LelylanController($scope, Device) {
var params = {
id: '<id>',
function: '<set-intensity>',
properties:
[ { id: '<intensity>',
value: '90' } ] };
$scope.device = new Device(params);
$scope.device.$execute();
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-ii-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
params = {
function: 'https://api.lelylan.com/functions/<set-intensity>',
properties:
[ { uri: 'https://api.lelylan.com/properties/<intensity>',
value: '90' } ] };
device = lelylan.execute('<id>', params)</xmp></pre>
</div>
</div>
<div class="tab-pane" id="execute-a-function-ii-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = {
function: 'https://api.lelylan.com/functions/<set-intentity>',
properties:
[ { uri: 'https://api.lelylan.com/properties/<intensity>',
value: '90' } ] };
from lelylan import devices
device = devices.exec_dev_func('<id>', params)</xmp></pre>
</div>
</div>
</div>
<p class="notice">
<span class="label">Notice</span>
To deeply understand how functions work check out the
<a href="/api/types/functions">functions API</a>.
</p>
<%= render 'shared/content/physical_not_physical' %>
<h3>Example body response</h3>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<% end %>
<hr>
<h2 id="activate-a-device">POST /activations</h2>
<p>
Activate a device through its activation code and returns extended information for it.
</p>
<div class="alert alert-info">
<p>
<span class="label label-lelylan">notice</span>
When you create a device you own it. To let others own your
devices <a href="#deactivate-a-device">deactivate</a> them first.
</p>
</div>
<h3>Resource URL</h3>
<pre><code>POST https://api.lelylan.com/activations</code></pre>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td class="parameter">
activation_code
<span class="info">required</span>
</td>
<td>
Device activation code.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class=" active"><a href="#activate-a-device-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#activate-a-device-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#activate-a-device-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#activate-a-device-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#activate-a-device-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="activate-a-device-curl">
<div class="preview"><pre><xmp>curl -X POST https://api.lelylan.com/activations \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{ "activation_code": "<activation-code>" }'</xmp></pre></div>
</div>
<div class="tab-pane" id="activate-a-device-node">
<div class="preview">
<pre class="prettyprint"><xmp>var Lelylan = require('lelylan-node')({ token: token });
var params = { activation_code: '<activation-code>' };
Lelylan.Device.activate(params, callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="activate-a-device-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{activated}}</div>
<script>
function LelylanController($scope, Activation) {
var params = { activation_code: '<activation-code>' };
Activation.activate(params).success(function(response) { $scope.activated = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="activate-a-device-ruby">
<div class="preview">
<pre class="prettyprint"><xmp>lelylan = Lelylan::Client.new(token: token)
params = { activation_code: '<activation-code>' }
device = lelylan.activate_device(params)</xmp></pre>
</div>
</div>
<div class="tab-pane" id="activate-a-device-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = { activation_code: '<activation-code>' }
from lelylan import activations
device = activations.activate_dev(params)</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<div class="code-block"><pre><code>HTTP/1.1 201 Created
Location: https://api.lelylan.com/devices/5042344b95fc441000000001</code></pre></div>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>
<h3>What if the device is already activated?</h3>
<p>
Trying to activate a device already activate will return a not valid response.
</p>
<div class="code-block">
<pre><code>HTTP/1.1 422 Not Valid
<hr>
{
"status": "422",
"method": "POST",
"request": "https://api.lelylan.com/activations",
"error": {
"code": "notifications.resource.already_activated",
"description": "Resource already activated",
"body": { "activation_code": "3cd6360a163b112c5eb910967c5866f77f019694" }
}
}</code></pre>
</div>
<hr>
<h2 id="deactivate-a-device">DELETE /activations/:activation-code</h2>
<p>
Deactivate a device identified from its activation code and returns extended information for it.
When a device is deactivated, anyone owning the activation code can claim the device ownership.
Until the claim happents, the previous owner remains.
</p>
<h3>Resource URL</h3>
<pre><code>DELETE https://api.lelylan.com/activations/:activation-code</code></pre>
<h3>Parameters</h3>
<table class="table table-stripped table-hover">
<tbody>
<tr>
<td class="parameter">
activation_code
<span class="info">required</span>
</td>
<td>
The <a href="/api#get-a-device-private-info">activation code</a> of the desired device.
</td>
</tr>
</tbody>
</table>
<h3>Example Request</h3>
<ul class="nav nav-tabs">
<li class="active"><a href="#deactivate-a-device-curl" data-toggle="tab" class="curl">Curl</a></li>
<li><a href="#deactivate-a-device-node" data-toggle="tab" class="node">Node.js</a></li>
<li><a href="#deactivate-a-device-angular" data-toggle="tab" class="angular">AngularJS</a></li>
<li><a href="#deactivate-a-device-ruby" data-toggle="tab" class="ruby">Ruby</a></li>
<li><a href="#deactivate-a-device-python" data-toggle="tab" class="python">Python</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="deactivate-a-device-curl">
<div class="preview"><pre><xmp>curl -X DELETE https://api.lelylan.com/activations/<activation-code> \
-H 'Authorization: Bearer <token>'</xmp></pre>
</div>
</div>
<div class="tab-pane" id="deactivate-a-device-node">
<div class="preview">
<pre><xmp class="prettyprint">var Lelylan = require('lelylan-node')({ token: token });
Lelylan.Device.deactivate('<activation-code>', callback);</xmp></pre>
</div>
</div>
<div class="tab-pane" id="deactivate-a-device-angular">
<div class="preview">
<pre class="prettyprint"><xmp><html ng-app="lelylan.client">
<body>
<!-- login component here (dev.lelylan.com/api/oauth#implicit-grant-angular) -->
<div ng-controller="LelylanController">{{deactivated}}</div>
<script>
function LelylanController($scope, Deactivation) {
var params = { activation_code: '<activation-code>' };
Activation.deactivate('1').success(function(response) { $scope.deactivated = response })
}
</script>
</body>
</html></xmp></pre>
</div>
</div>
<div class="tab-pane" id="deactivate-a-device-ruby">
<div class="preview">
<pre><xmp class="prettyprint">lelylan = Lelylan::Client.new(token: token)
device = lelylan.deactivate_device('<activation-code>')</xmp></pre>
</div>
</div>
<div class="tab-pane" id="deactivate-a-device-python">
<div class="preview">
<pre class="prettyprint"><xmp>oauth.set_access_token()
params = { activation_code: '<activation-code>' }
from lelylan import activations
device = activations.deactivate_dev(params)</xmp></pre>
</div>
</div>
</div>
<h3>Example header response</h3>
<pre><code>HTTP/1.1 200 OK</code></pre>
<h3>Example body response</h3>
<p>
See <a href="#device-representation">device representation</a> for body response.
</p>