Devices

The following resources are applicable:

/devices

Mount Point: /v2/devices

GET

Returns the list of all the Devices that connected under the account of the currently connected user. For each returned Device, its latest Device profile will be returned.

If the flag DevicesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more devices exist and can be read by moving the offset forward in a new request

Example to get all devices:

String apiPath = "devices.xml";
WebResource apisWeb = client.resource(API_URL).path(apiPath);

DevicesResult result;
int offset = 0;
do {
// if the "limit" queryParam is not initialized, limit default value = 50
// if the "offset" queryParam is not initialized, offset default value = 0
apisWeb = apisWeb.queryParam("limit", "" + limit);
if (offset > 0)
apisWeb = apisWeb.queryParam("offset", "" + offset);
result = apisWeb.get(DevicesResult.class);
offset += limit;
} while (result.isLimitExceeded()):

Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices.xml | xmllint --format -

Parameters

name description type default
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0

Response Body

element: devicesResult
media types: application/xml
application/json

The list of requested Devices.

POST

Creates a new Device based on the information provided in DeviceCreator parameter.

Request Body

element: deviceCreator
media types: application/xml
application/json

Provides the information for the new Device to be created.

Response Body

element: device
media types: application/xml
application/json

The newly created Device.

/devices/{clientId}

Mount Point: /v2/devices/{clientId}

The following operations are supported on this resource:

GET

Returns the Device identified by the specified ClientID under the account of the currently connected user.

Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}.xml | xmllint --format -

Parameters

name description type default
clientId The client ID of the device requested. path

Response Body

element: device
media types: application/xml
application/json

The list of requested devices.

PUT

Updates the Device specified by the "clientId" path parameter based on the information provided in the Device request body.

Parameters

name description type default
clientId The id of the Device to be updated. path

Request Body

element: device
media types: application/xml
application/json

The modified Device whose attributes need to be updated.

Response Body

element: device
media types: application/xml
application/json

The updated Device.

DELETE

Deletes the Device specified by the "clientId" path parameter.

Parameters

name description type default
clientId The id of the Device to be deleted. path

/devices/{clientId}/command

Mount Point: /v2/devices/{clientId}/command

POST

Executes a remote command on a device and return the command output.

Example to list all files in the current working directory:

Client client = client();
WebResource apisWeb = client.resource(APIS_TEST_URL);
WebResource.Builder deviceCommandWebXml = apisWeb.path("devices")
.path(s_clientId)
.path("command")
.accept(MediaType.APPLICATION_XML)
.type(MediaType.APPLICATION_XML);

DeviceCommandInput commandInput = new DeviceCommandInput();
commandInput.setCommand("ls");
commandInput.setArguments(new String[] { "-l", "-a" });

DeviceCommandOutput commandOutput = deviceCommandWebXml.post(DeviceCommandOutput.class, commandInput);

Example of query in CURL. The command input XML request body is read from file:
curl --user 'username:password' -X POST -H 'Content-type: application/xml' -d @command.xml -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/command.xml | xmllint --format -

Parameters

name description type default
clientId The client ID of the Device requested. path

Request Body

element: commandInput
media types: application/xml
application/json

(no documentation provided)

Response Body

element: commandOutput
media types: application/xml
application/json

The command output.

/devices/{clientId}/configurations

Mount Point: /v2/devices/{clientId}/configurations

GET

Returns the configuration of a device or the configuration of the OSGi component identified with specified PID (service's persistent identity). In the OSGi framework, the service's persistent identity is defined as the name attribute of the Component Descriptor XML file; at runtime, the same value is also available in the component.name and in the service.pid attributes of the Component Configuration.

Example of query in CURL:
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/configurations.xml?componentId={componentId} | xmllint --format -

Parameters

name description type default
clientId The client ID of the device requested. path
componentId The PID (service's persistent identity) of the OSGi component requested. query

Response Body

element: configurations
media types: application/xml
application/json

The requested configuration.

POST

Updates the configuration of the registered OSGi component with the specified pid.

Example of query in CURL. This example reads the configuration from file:
curl --user 'username:password' -X POST -H 'Content-type: application/xml' -d @configuration.xml -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/configurations

Parameters

name description type default
clientId The client ID of the Device requested. path

Request Body

element: configurations
media types: application/xml

The device configuration.

/devices/{clientId}/events

Mount Point: /v2/devices/{clientId}/events

GET

Returns the events for the device identified by the specified ClientID under the account of the currently connected user.

If the flag DeviceEventsResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more events exist and can be read by moving the offset forward in a new request

Example of query in CURL:
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/events.xml | xmllint --format -

Parameters

name description type default
clientId The client ID of the device requested. path
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0
startDate Start date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. The default value of 0 means no start date. Alternatively, the date can be expressed as a string following the ISO 8601 format. query 0
endDate End date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. The default value of 0 means no end date. Alternatively, the date can be expressed as a string following the ISO 8601 format. query 0

Response Body

element: deviceEventsResult
media types: application/xml
application/json

The list of requested events.

/devices/{clientId}/packages

Mount Point: /v2/devices/{clientId}/packages

GET

Returns the list of packages deployed on a device.

Example of query in CURL:
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/packages.xml | xmllint --format -

Parameters

name description type default
clientId The client ID of the Device requested. path

Response Body

element: packages
media types: application/xml
application/json

(no documentation provided)

POST

Install a new deployment package on a device.

Example of query in CURL: curl --user 'username:password' -X POST https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/packages?packageUrl={packageUrl}

Parameters

name description type default
clientId The client ID of the Device requested. path
packageUrl Mandatory parameter with the URL of the package to install. query

/devices/{clientId}/packages/{packageName}

Mount Point: /v2/devices/{clientId}/packages/{packageName}

DELETE

Uninstalls a package deployed on a device.

Example of query in CURL:
curl --user 'username:password' -X DELETE -k https://api-sandbox.everyware-cloud.com/v2/devices/F0:DE:F1:C4:53:DB/packages/{packageName}

Parameters

name description type default
clientId The client ID of the Device requested. path
packageName (no documentation provided) path

/devices/{clientId}/rollback

Mount Point: /v2/devices/{clientId}/rollback

POST

Updates the configuration of a device rolling back a given snapshot ID.

Example of query in CURL:
curl --user 'username:password' -X POST https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/rollback?snapshotId={snapshotId}

Parameters

name description type default
clientId The client ID of the Device requested. path
snapshotId (no documentation provided) query

/devices/{clientId}/snapshots

Mount Point: /v2/devices/{clientId}/snapshots

GET

Returns the list of snapshot (older configurations) IDs of the device.

Example of query in CURL:
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/snapshots.xml | xmllint --format -

Parameters

name description type default
clientId The client ID of the Device requested. path

Response Body

element: snapshotIdsResult
media types: application/xml
application/json

(no documentation provided)

/devices/{clientId}/snapshots/{snapshotId}

Mount Point: /v2/devices/{clientId}/snapshots/{snapshotId}

GET

Returns an older configuration of a device from a given snapshot ID.

Example of query in CURL:
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/snapshots/{snapshotId}.xml | xmllint --format -

Parameters

name description type default
clientId The client ID of the Device requested. path
snapshotId (no documentation provided) path

Response Body

element: configurations
media types: application/xml
application/json

(no documentation provided)

/devices/{clientId}/wakeupSMS

Mount Point: /v2/devices/{clientId}/wakeupSMS

POST

Sends a wakeup SMS to ay device identified by the value of the "clientId" parameter. More in detail the call allows to request to the SIM provider M2M platform to send a wakeup sms to a device. A positive reply from the SIM provider M2M platform doesn't confirm the delivery of the SMS to the device, but only that the M2M platform takes in charge of send the wakeup SMS to the device. Example of query in CURL.
curl --user 'username:password' -X POST -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/wakeupSMS

Parameters

name description type default
clientId The client ID of the Device addressee of the wakeup SMS. path

/devices/connectionSummary

Mount Point: /v2/devices/connectionSummary

GET

Returns an aggregated summary of the connection status of a group of devices at a point in time. It returns the number of devices currently connected, the number of devices which disconnect cleanly, the number of devices which disconnected abruptly, and the number of devices which have been disabled.

Parameters

name description type default
tag Optional, the name of the Tag that will be used to select the devices whose aggregated status is requested query

Response Body

element: deviceConnectionSummary
media types: application/xml
application/json

The DeviceConnectionSummary

/devices/search

Mount Point: /v2/devices/search

GET

Searches the device registry for devices based on the specified criteria. Query parameters are used to defined the filtering predicate, the sorting and the pagination. The supplied query parameters are combined into a logical AND, so all specified conditions need to be satisfied for the device to be selected and returned. Query parameters which allow for multiple values are combined into an IN predicate effectively combining them into a logical OR of the values supplied.

The "fetch" query parameter can be used to control the amount of information to be loaded and returned for each device. Allowed values are "BASIC" or "FULL". With "BASIC", the core attributes of the device and the version information of its profile are returned. With "FULL", all the additional device extended properties are loaded and returned.

The returned devices can be sorted. Allowed values for the sortField query parameter are: "clientId", "displayName", "lastEventOn". Sorting can be specified ascending or descending using the "sort" query parameter with values: "asc" or "desc". If no sortField is specified, the returned devices will not follow any specific order.

If the flag DevicesResult.limitExceeded is set, the maximum number of entries to be returned has been reached. More data exist and can be read by moving the offset forward in a new request

Parameters

name description type default
clientId One or more clientId for the devices to be returned. query
serialNumber One or more serial number for the devices to be returned. query
displayName One or more display name for the devices to be returned. query
imei One or more IMEI for the devices to be returned. query
imsi One or more IMSI for the devices to be returned. query
iccid (no documentation provided) query
modelId The id of the model of the devices to be returned. query
connectionIp The connectionIp of the devices to be returned. query
status The device status (Enabled/Disabled) of the devices to be returned. query
connectionStatus The device connection status of the devices to be returned. query
esfVersion The version of ESF for the devices to be returned. query
applicationIdentifier The application identifiers of the devices to be returned. query
customAttribute1 The value of customAttribute1 for the devices to be returned. query
customAttribute2 The value of customAttribute2 for the devices to be returned. query
tag The name of the Tag applied to the devices to be returned. query
sortField Optional sorting of the returned devices. Allowed values are: "clientId", "displayName", "lastEventOn". query
signedCertificateId The certificate id installed on the devices to be returned. query
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0
fetch Specifies the amount of information requested. Allowed values are "BASIC" or "FULL". With "BASIC", the core attributes of the device and the version information of its profile are returned. With "FULL", all the additional extended attributes are loaded and returned. query BASIC
sort (no documentation provided) query desc

Response Body

element: devicesResult
media types: application/xml
application/json

The list of devices matching the criteria supplied.

/devices/sendRequest

Mount Point: /v2/devices/sendRequest

The following operations are supported on this resource:

GET

Sends a request message to a device and waits for a response synchronously. This call is generally used to perform remote management of resources attached to the device such sensors and registries. The target device is identified by the supplied topic. The topic is structured like the following:

$EDC / account_name / client_id / app_id / verb / resource - id

To ensure the delivery of request messages, it is expected that each application that supports request/response conversations via MQTT subscribe to the following topic on device startup:
$EDC/account_name/client_id/app_id/#
. Everyware Cloud clients like Everyware Software Framework (ESF) and Eclipse Kura do offer this behavior by default. The sendRequest method will proceed to the initiation of a request/response conversation by:
  1. Generate a conversation identifier - "request.id" - for example by concatenating a random number to a timestamp
  2. Subscribe to the topic where the response message will be published to, where requester.client.id is the Client ID of the requester:
    $EDC / account_name / requester.client.id / app_id / REPLY / request.id
    
  3. Send the request message to the appropriate application-specific topic including the following fields in the payload:
    • request.id: identifier used to match a response with a request.
    • requester.client.id: the client ID of the issuer of the request.
The application receiving the request will process it and respond on a REPLY topic structured as:
$EDC / account_name / requester.client.id / app_id / REPLY / request.id
. Once the response for a given request is received, the requester should unsubscribe from the REPLY topic. The returned response will be an EdcPayload structure with three additional well-known metrics:

In the following example we will request the current configuration to an ESF device connected under the current account:

curl --user 'username:password' -H "Accept: application/xml" -H "Content-Type: application/xml" -X GET 'https://api-sandbox.everyware-cloud.com/v2/devices/sendRequest.xml?topic=$EDC/edcguest/B8:E8:56:2A:BA:24/CONF-V1/GET/configurations'
In this specified case, the remote application will package the configurations of the services running in the target device in the body of the returned EdcResponsePayload. As all EdcMessage bodies, the returned XML service configurations will be serialized as an base64-encoded inline String in the body element.

Parameters

name description type default
topic Target device and application. It is expressed with a structure like:
$EDC / account_name / client_id / app_id / verb / resource - id
query
timeout (no documentation provided) query 0

Response Body

element: edcResponsePayload
media types: application/xml
application/json

EdcResponsePayload response received from the remote device.

POST

Sends a request message to a device and waits for a response synchronously. This call is generally used to perform remote management of resources attached to the device such sensors and registries. The target device is identified by the topic specified under the provided requestMessage. The topic is structured like the following:

$EDC / account_name / client_id / app_id / verb / resource - id

To ensure the delivery of request messages, it is expected that each application that supports request/response conversations via MQTT subscribe to the following topic on device startup:
$EDC/account_name/client_id/app_id/#
. Everyware Cloud clients like Everyware Software Framework (ESF) and Eclipse Kura do offer this behavior by default. The sendRequest method will proceed to the initiation of a request/response conversation by:
  1. Generate a conversation identifier - "request.id" - for example by concatenating a random number to a timestamp
  2. Subscribe to the topic where the response message will be published to, where requester.client.id is the Client ID of the requester:
    $EDC / account_name / requester.client.id / app_id / REPLY / request.id
    
  3. Send the request message to the appropriate application-specific topic including the following fields in the payload:
    • request.id: identifier used to match a response with a request.
    • requester.client.id: the client ID of the issuer of the request.
The application receiving the request will process it and respond on a REPLY topic structured as:
$EDC / account_name / requester.client.id / app_id / REPLY / request.id
. Once the response for a given request is received, the requester should unsubscribe from the REPLY topic. The returned response will be an EdcPayload structure with three additional well-known metrics:

In the following example we will request the current configuration to an ESF device connected under the current account:

curl --data '$EDC/edcguest/B8:E8:56:2A:BA:24/CONF-V1/GET/configurations' --user 'username:password' -H "Accept: application/xml" -H "Content-Type: application/xml" -X POST 'http://localhost:8080/edc-rest-apis/v2/devices/sendRequest.xml'
In this specified case, the remote application will package the configurations of the services running in the target device in the body of the returned EdcResponsePayload. As all EdcMessage bodies, the returned XML service configurations will be serialized as an base64-encoded inline String in the body element.

Parameters

name description type default
timeout (no documentation provided) query 0

Request Body

element: message
media types: application/xml

(no documentation provided)

Response Body

element: edcResponsePayload
media types: application/xml
application/json

EdcResponsePayload response received from the remote device.

POST

Sends a request message to a device and waits for a response synchronously. This call is generally used to perform remote management of resources attached to the device such sensors and registries. The target device is identified by the topic specified under the provided requestMessage. The topic is structured like the following:

$EDC / account_name / client_id / app_id / verb / resource - id

To ensure the delivery of request messages, it is expected that each application that supports request/response conversations via MQTT subscribe to the following topic on device startup:
$EDC/account_name/client_id/app_id/#
. Everyware Cloud clients like Everyware Software Framework (ESF) and Eclipse Kura do offer this behavior by default. The sendRequest method will proceed to the initiation of a request/response conversation by:
  1. Generate a conversation identifier - "request.id" - for example by concatenating a random number to a timestamp
  2. Subscribe to the topic where the response message will be published to, where requester.client.id is the Client ID of the requester:
    $EDC / account_name / requester.client.id / app_id / REPLY / request.id
    
  3. Send the request message to the appropriate application-specific topic including the following fields in the payload:
    • request.id: identifier used to match a response with a request.
    • requester.client.id: the client ID of the issuer of the request.
The application receiving the request will process it and respond on a REPLY topic structured as:
$EDC / account_name / requester.client.id / app_id / REPLY / request.id
. Once the response for a given request is received, the requester should unsubscribe from the REPLY topic. The returned response will be an EdcPayload structure with three additional well-known metrics:

In the following example we will request the current configuration to an ESF device connected under the current account in JSON format:

curl --data '{"topic":"$EDC/edcguest/B8:E8:56:2A:BA:24/CONF-V1/GET/configurations","payload":{}}' --user 'edcguest:Welcome1' -H "Accept: application/json" -H "Content-Type: application/json" -X POST 'http://localhost:8080/edc-rest-apis/v2/devices/sendRequest.json'
In this specified case, the remote application will package the configurations of the services running in the target device in the body of the returned EdcResponsePayload. As all EdcMessage bodies, the returned XML service configurations will be serialized as an base64-encoded inline String in the body element.

Parameters

name description type default
timeout (no documentation provided) query 0

Request Body

element: requestMessage
media types: application/json

(no documentation provided)

Response Body

element: edcResponsePayload
media types: application/xml
application/json

EdcResponsePayload response received from the remote device.