Skip to content
This repository was archived by the owner on Jun 25, 2024. It is now read-only.

Device Management

Jump to bottom
Joanna Rozestwinska edited this page Feb 15, 2015 · 16 revisions

List all Devices

Get a list of all devices for the specified account, with minimal data for each device

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d 
GET /accounts/{accountId}/devices

Response 200 (application/json)    
[
    { 
        "deviceId": "24-a5-80-21-5b-29",
        "gatewayId": "24-a5-80-21-5b-29",
        "name": "Device #1",  
        "tags": ["Israel", "Tel Aviv"],
        "status": "created",
    },
    { 
        "deviceId": "24-a5-80-21-5b-30",
        "gatewayId": "24-a5-80-21-5b-30",
        "name": "Device #2",  
        "tags": ["US", "Oregon", "Portland"],
        "status": "active",
    },
    { 
        "deviceId": "24-a5-80-21-5b-3a",
        "gatewayId": "24-a5-80-21-5b-3a",
        "name": "Device #3",  
        "tags": ["US", "California", "Folsom"],
        "status": "created",
    }
]

Get one Device

Get full detail for specific device for the specified account.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d
deviceId URL Slug The ID of a Device 24-a5-80-21-5b-29 
GET /accounts/{accountId}/devices/{deviceId}

Response 200 (application/json)
{
        "deviceId": "24-a5-80-21-5b-29",
        "gatewayId": "24-a5-80-21-5b-29",
        "name": "Device 1",
        "status": "active",
        "created": 1404250013693,
        "components": [
            {
                "cid": "73f9fe37-bd9e-4139-b678-afdd716e7dda",
                "name": "temp",
                "type": "temperature.v1.0"
            }
        ],
        "attributes": {
            "vendor": "intel",
            "platform": "x86",
            "os": "linux"
       }
}

Create a Device

Used to create a device. The access token in the header will be used to authenticate the account on the URL for which this operation is being performed.

Location is optional and only makes sense for stationary devices. It should be sent as [decimal latitude, decimal longitude, (optional) height in meters] using WGS84 Datum.

Device attributes should be sent as key:value pairs, where both key and value are string

The gatewayId should be the same as the deviceId

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
Content-Type HTTP Header Type of body content application/json
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d 
POST /accounts/{accountId}/devices
{ 
	"deviceId": "24-a5-80-21-5b-29",
	"gatewayId": "24-a5-80-21-5b-29",
	"name": "Device #1",            
	"tags": ["US", "California", "Sacramento"],
	"loc": [ 45.5434085, -122.654422, 124.3 ],
	"attributes": {
		"vendor": "intel",
		"platform": "x86",
		"os": "linux"
	}
}

Response 201 (CREATED) application/json
{ 
	"deviceId": "24-a5-80-21-5b-29",
	"gatewayId": "24-a5-80-21-5b-29",
	"name": "Device #1",            
	"tags": ["US", "California", "Sacramento"],
	"loc": [ 45.5434085, -122.654422, 124.3 ],
	"created": 1354741966688,
	"status": "created",
	"attributes": {
		"vendor": "intel",
		"platform": "x86",
		"os": "linux"
	}
}

Errors

Error code HTTP status code Rationale
1409 409 Device already exists
1410 400 Invalid activation code (did activation code expire?)

Update One Device

Update a single device. The device ID (deviceId) cannot be updated as it is the key. If the device id does not exist, an error will be returned. The list of components represents the entire list of components for the device.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
Content-Type HTTP Header Type of body content application/json
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d
deviceId URL Slug The ID of a Device 24-a5-80-21-5b-29 
PUT /accounts/{acountId}/devices/{deviceId}
{
        "gatewayId": "24-a5-80-21-5b-29",
        "name": "Device #1",
        "loc": [ 45.5434085, -122.654422, 124.3 ],  
        "tags": ["Arizona", "Phoenix"],            
        "attributes": {
                "vendor": "intel",
                "platform": "x86",
                "os": "linux"
        }
     } 

Response 200 (application/json)
{
        "gatewayId": "24-a5-80-21-5b-29",
        "name": "Device #1",
        "loc": [ 45.5434085, -122.654422, 124.3 ],  
        "tags": ["Arizona", "Phoenix"],            
        "attributes": {
                "vendor": "intel",
                "platform": "x86",
                "os": "linux"
        }
     }

Errors

Error code HTTP status code Rationale
1404 404 Device to be updated does not exist

Activate one Device

Activates a specific device for the specified account.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d
Content-Type HTTP Header Type of body content application/json
deviceId URL Slug The ID of a Device 24-a5-80-21-5b-29 
PUT /accounts/{acountId}/devices/{deviceId}/activation
{ 
     "activationCode": "jq4h6d2b"
}

Response 200 (application/json)
{
    "deviceToken":"eyJ0eX......",
    "accountId":"ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d"
}

The device token should be stored permanently. You will need it to add components to a device and send measurements.

Errors

Error code HTTP status code Rationale
1410 400 Invalid activation code
1510 500 Internal server error during activation

Delete one Device

Delete a specific device for this account. All data from all time series associated with the device will be deleted.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d
deviceId URL Slug The ID of a Device 24-a5-80-21-5b-29 
DELETE /accounts/{accountId}/devices/{deviceId}

Response 204

Add a Component to a device

Add component to an specific device. A component represents either a time series or an actuator. The type must already existing in the Component Type catalog. You can see the entries in the catalog with this call: Component-Types-Catalog#list-all-component-types-for-an-account. Or, in the UI, go to the "Account" page and click the "Catalog" tab. Make sure you use in headers Device Token received during device activation process and not Access Token for your user.

Param Type Description Value
Authorization HTTP Header Device Token Authorization: Bearer eyJ0eX...
Content-Type HTTP Header Type of body content application/json
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d
deviceId URL Slug The ID of a Device 24-a5-80-21-5b-29 
POST /accounts/{accountId}/devices/{deviceId}/components
{ 
	"cid": "436e7e74-6771-4898-9057-26932f5eb7e1",
	"name": "temp",
	"type": "temperature.v1.0"
}

Response 201 (CREATED) application/json
{ 
	"cid": "436e7e74-6771-4898-9057-26932f5eb7e1",
	"name": "Temperature Sensor 1",
	"type": "temperature.v1.0"
}

Errors

Error code HTTP status code Rationale
1411 409 Component already exists

Delete one Component

Delete a specific component for a specific device. All data will be unavailable.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d
deviceId URL Slug The ID of a Device 436e7e74-6771-4898-9057-26932f5eb7e1
cid URL Slug The ID of the component to delete 24-a5-80-21-5b-29 
DELETE /accounts/{accountId}/devices/{deviceId}/components/{cid}

Response 204

Errors

Error code HTTP status code Rationale
1404 404 Device not found
1412 404 Component to be deleted does not exist

List all tags for Devices

Get a list of all tags from devices for the specified account.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d 
GET /accounts/{accountId}/devices/tags

Response 200 (application/json)    
[     
    "tag",
    "tag2"
]

List all attributes of Devices

Get a list of all devices's attribute for the specified account.

Param Type Description Value
Authorization HTTP Header Access Token Authorization: Bearer eyJ0eX...
accountId URL Slug The ID of an Account ed6c80f7-1914-4d21-bc26-47d0bb5fdf4d 
GET /accounts/{accountId}/devices/attributes

Response 200  
{
"Firmware Version": [
    "3.13.0-32-generic"
],
"Model Name": [
    "x64"
],
"agent_version": [
    "1.5.0"
],
"attribute": [
    "value"
],
"hardware_model": [
    "linux"
],
"hardware_vendor": [
    "Intel(R) Xeon(R) CPU E5-2680 0 @ 2.70GHz"
]
}
Clone this wiki locally