Skip to content
This repository has been archived by the owner on Jan 8, 2024. It is now read-only.

Device Management

Jump to bottom
wagmarcel edited this page Jan 10, 2018 · 1 revision

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",
    }
]

List filtered Devices

Get a list of all devices for the specified account filtered by provided parameters, 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
sort HTTP parameter Optional Result will be sorted by this field deviceId/gatewayId/name/status
order HTTP parameter Optional Sorting order asc/desc
limit HTTP parameter Optional Maximum number of returned devices positive integer
skip HTTP parameter Optional Returned list offset - if 10 provided, result won't contain first 10 list elements retrieved from database. Default is 0 positive integer
deviceId/gatewayId/name/status HTTP parameter Optional Filter the result by specific field and value (example: status=created) desired value - depends on the field 
GET /accounts/{accountId}/devices?status=created&sort=name&order=desc&limit=1&skip=1

Response 200 (application/json)    
[
    { 
        "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.

Device ID should consist only A-Z, a-z, 0-9 and - characters 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

Device attributes collection can not contain keys: deviceId, deviceName, gatewayId, tags, location, components.

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
cid Message Parameter Unique component ID (user-provided) 436e7e74-6771-4898-9057-26932f5eb7e1
name Message Parameter Component Name temp
type Message Parameter Component Type temperature.v1.0 
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"
}

Parameter descriptions

Attribute description value
cid component ID user-defined UUID unique in the whole system - if alreasy exists, error 409 will be returned
name component name user-defined name of component
type type of component component type - available component types are available in component list for your account

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"
]
}

Advanced count of Devices

Counts devices's based on filters.

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 
POST /accounts/{accountId}/devices/count
{
	"status":{
		"operator":"like",
		"value":""
	},
	"components":{
		"operator":"exists",
		"value": "false"
		}
}

Response 200  
{
	"device": {
		"total": 1
	}
}

Advanced search of Devices

Search devices's based on filters and query parameters.

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
limit Integer Max size of requested devices 10
skip Integer Number of skipped devices 0 
POST /accounts/{accountId}/devices/search?limit=10&skip=0
{
	"status":{
		"operator":"like",
		"value":""
	},
	"components":{
		"operator":"exists",
		"value": "false"
		}
}

Response 200  
[
	{
		"created": 1427365983710,
		"deviceId": "dev1",
		"gatewayId": "dev1",
		"loc": [
			58.30452,
			18.50052,
			121
		],
		"name": "Sample device 1",
		"status": "active",
		"tags": [
			"test"
		]
	}
]

Table of Contents

Clone this wiki locally