Devices Resource

GET /devices

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 -

Request Parameters
name type description default constraints
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required
offset query Starting index offset for the entries to be returned. For example if '5' is specified, it will skip the first 5 entries and start with the 6th entry, up to the limit. Note that an error will be returned if the maximum allowed value is exceeded. 0 required
startId query Starting offset for the entries to be returned. This is specified as the device id and will return entries after the specified id. To iterate through all entries, specify the id for the last entry from the last set of results.    
Response Body
media type data type description
application/json DevicesResult (JSON) The list of requested Devices.
application/xml devicesResult (XML)

Example

Request
GET /devices
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "device" : [ {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "DISABLED",
    "connectionStatus" : "CONNECTED",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "lastEventOn" : 12345,
    "lastEventType" : "CMD_EXECUTED",
    "displayName" : "...",
    "serialNumber" : "...",
    "imei" : "...",
    "imsi" : "...",
    "iccid" : "...",
    "modelId" : "...",
    "connectionIp" : "...",
    "biosVersion" : "...",
    "firmwareVersion" : "...",
    "osVersion" : "...",
    "jvmVersion" : "...",
    "osgiFrameworkVersion" : "...",
    "esfVersion" : "...",
    "applicationIdentifiers" : "...",
    "acceptEncoding" : "...",
    "gpsLatitude" : 12345.0,
    "gpsLongitude" : 12345.0,
    "customAttribute1" : "...",
    "customAttribute2" : "...",
    "customAttribute3" : "...",
    "customAttribute4" : "...",
    "customAttribute5" : "...",
    "optlock" : 12345,
    "uptime" : 12345,
    "modelName" : "...",
    "partNumber" : "...",
    "availableProcessors" : "...",
    "totalMemory" : "...",
    "os" : "...",
    "osArch" : "...",
    "jvmName" : "...",
    "jvmProfile" : "...",
    "osgiFramework" : "...",
    "connectionInterface" : "...",
    "gpsAltitude" : 12345.0,
    "deviceUserId" : 12345,
    "accountName" : "...",
    "signedCertificateId" : 12345,
    "mqttConnectionIp" : "...",
    "credentialsTight" : "LOOSE",
    "credentialsAllowChange" : true,
    "certificateCommonName" : "...",
    "brokerClusterId" : 12345
  }, {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "ENABLED",
    "connectionStatus" : "CONNECTED",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "lastEventOn" : 12345,
    "lastEventType" : "CONF_ROLLEDBACK",
    "displayName" : "...",
    "serialNumber" : "...",
    "imei" : "...",
    "imsi" : "...",
    "iccid" : "...",
    "modelId" : "...",
    "connectionIp" : "...",
    "biosVersion" : "...",
    "firmwareVersion" : "...",
    "osVersion" : "...",
    "jvmVersion" : "...",
    "osgiFrameworkVersion" : "...",
    "esfVersion" : "...",
    "applicationIdentifiers" : "...",
    "acceptEncoding" : "...",
    "gpsLatitude" : 12345.0,
    "gpsLongitude" : 12345.0,
    "customAttribute1" : "...",
    "customAttribute2" : "...",
    "customAttribute3" : "...",
    "customAttribute4" : "...",
    "customAttribute5" : "...",
    "optlock" : 12345,
    "uptime" : 12345,
    "modelName" : "...",
    "partNumber" : "...",
    "availableProcessors" : "...",
    "totalMemory" : "...",
    "os" : "...",
    "osArch" : "...",
    "jvmName" : "...",
    "jvmProfile" : "...",
    "osgiFramework" : "...",
    "connectionInterface" : "...",
    "gpsAltitude" : 12345.0,
    "deviceUserId" : 12345,
    "accountName" : "...",
    "signedCertificateId" : 12345,
    "mqttConnectionIp" : "...",
    "credentialsTight" : "INHERITED",
    "credentialsAllowChange" : true,
    "certificateCommonName" : "...",
    "brokerClusterId" : 12345
  } ]
}
                
              

POST /devices

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

Request Body
media type data type description
application/json DeviceCreator (JSON) Provides the information for the new Device to be created.
application/xml deviceCreator (XML)
Response Body
media type data type description
application/json Device (JSON) The newly created Device.
application/xml device (XML)

Example

Request
POST /devices
Content-Type: application/json
Accept: application/json

                
{
  "accountId" : 12345,
  "deviceUserId" : 12345,
  "clientId" : "...",
  "displayName" : "...",
  "modelId" : "...",
  "serialNumber" : "...",
  "imei" : "...",
  "imsi" : "...",
  "iccid" : "...",
  "firmwareVersion" : "...",
  "biosVersion" : "...",
  "osVersion" : "...",
  "jvmVersion" : "...",
  "osgiFrameworkVersion" : "...",
  "esfVersion" : "...",
  "connectionIp" : "...",
  "acceptEncoding" : "...",
  "applicationIdentifiers" : "...",
  "gpsLatitude" : 12345.0,
  "gpsLongitude" : 12345.0,
  "customAttribute1" : "...",
  "customAttribute2" : "...",
  "customAttribute3" : "...",
  "customAttribute4" : "...",
  "customAttribute5" : "...",
  "properties" : "...",
  "signedCertificateId" : 12345,
  "credentialsTight" : "INHERITED",
  "credentialsAllowChange" : true,
  "certificateCommonName" : "..."
}
                
              
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "ENABLED",
  "connectionStatus" : "CONNECTED",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "lastEventOn" : 12345,
  "lastEventType" : "PROVISIONED",
  "displayName" : "...",
  "serialNumber" : "...",
  "imei" : "...",
  "imsi" : "...",
  "iccid" : "...",
  "modelId" : "...",
  "connectionIp" : "...",
  "biosVersion" : "...",
  "firmwareVersion" : "...",
  "osVersion" : "...",
  "jvmVersion" : "...",
  "osgiFrameworkVersion" : "...",
  "esfVersion" : "...",
  "applicationIdentifiers" : "...",
  "acceptEncoding" : "...",
  "gpsLatitude" : 12345.0,
  "gpsLongitude" : 12345.0,
  "customAttribute1" : "...",
  "customAttribute2" : "...",
  "customAttribute3" : "...",
  "customAttribute4" : "...",
  "customAttribute5" : "...",
  "optlock" : 12345,
  "uptime" : 12345,
  "modelName" : "...",
  "partNumber" : "...",
  "availableProcessors" : "...",
  "totalMemory" : "...",
  "os" : "...",
  "osArch" : "...",
  "jvmName" : "...",
  "jvmProfile" : "...",
  "osgiFramework" : "...",
  "connectionInterface" : "...",
  "gpsAltitude" : 12345.0,
  "deviceUserId" : 12345,
  "accountName" : "...",
  "signedCertificateId" : 12345,
  "mqttConnectionIp" : "...",
  "credentialsTight" : "STRICT",
  "credentialsAllowChange" : true,
  "certificateCommonName" : "...",
  "brokerClusterId" : 12345
}
                
              

GET /devices/connectionSummary

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.

Request Parameters
name type description
tag query Optional, the name of the Tag that will be used to select the devices whose aggregated status is requested
Response Body
media type data type description
application/json DeviceConnectionSummary (JSON) The DeviceConnectionSummary
application/xml deviceConnectionSummary (XML)

Example

Request
GET /devices/connectionSummary
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "connected" : 12345,
  "disconnected" : 12345,
  "missing" : 12345,
  "enabled" : 12345,
  "disabled" : 12345
}
                
              

GET /devices/search

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

Request Parameters
name type description default constraints multivalued
applicationIdentifier query The application identifiers of the devices to be returned.     no
clientId query One or more clientId for the devices to be returned.     yes
connectionIp query The connectionIp of the devices to be returned.     no
connectionStatus query The device connection status of the devices to be returned.     no
customAttribute1 query The value of customAttribute1 for the devices to be returned.     no
customAttribute2 query The value of customAttribute2 for the devices to be returned.     no
displayName query One or more display name for the devices to be returned.     yes
esfVersion query The version of ESF for the devices to be returned.     no
fetch query 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. BASIC   no
iccid query     yes
imei query One or more IMEI for the devices to be returned.     yes
imsi query One or more IMSI for the devices to be returned.     yes
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required no
modelId query The id of the model of the devices to be returned.     no
offset query Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 0 required no
serialNumber query One or more serial number for the devices to be returned.     yes
signedCertificateId query The certificate id installed on the devices to be returned.   long no
sort query desc   no
sortField query Optional sorting of the returned devices. Allowed values are: "clientId", "displayName", "lastEventOn".     no
status query The device status (Enabled/Disabled) of the devices to be returned.     no
tag query The name of the Tag applied to the devices to be returned.     no
Response Body
media type data type description
application/json DevicesResult (JSON) The list of devices matching the criteria supplied.
application/xml devicesResult (XML)

Example

Request
GET /devices/search
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "device" : [ {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "ENABLED",
    "connectionStatus" : "DISCONNECTED",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "lastEventOn" : 12345,
    "lastEventType" : "CONF_ROLLEDBACK",
    "displayName" : "...",
    "serialNumber" : "...",
    "imei" : "...",
    "imsi" : "...",
    "iccid" : "...",
    "modelId" : "...",
    "connectionIp" : "...",
    "biosVersion" : "...",
    "firmwareVersion" : "...",
    "osVersion" : "...",
    "jvmVersion" : "...",
    "osgiFrameworkVersion" : "...",
    "esfVersion" : "...",
    "applicationIdentifiers" : "...",
    "acceptEncoding" : "...",
    "gpsLatitude" : 12345.0,
    "gpsLongitude" : 12345.0,
    "customAttribute1" : "...",
    "customAttribute2" : "...",
    "customAttribute3" : "...",
    "customAttribute4" : "...",
    "customAttribute5" : "...",
    "optlock" : 12345,
    "uptime" : 12345,
    "modelName" : "...",
    "partNumber" : "...",
    "availableProcessors" : "...",
    "totalMemory" : "...",
    "os" : "...",
    "osArch" : "...",
    "jvmName" : "...",
    "jvmProfile" : "...",
    "osgiFramework" : "...",
    "connectionInterface" : "...",
    "gpsAltitude" : 12345.0,
    "deviceUserId" : 12345,
    "accountName" : "...",
    "signedCertificateId" : 12345,
    "mqttConnectionIp" : "...",
    "credentialsTight" : "LOOSE",
    "credentialsAllowChange" : true,
    "certificateCommonName" : "...",
    "brokerClusterId" : 12345
  }, {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "DISABLED",
    "connectionStatus" : "DISCONNECTED",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "lastEventOn" : 12345,
    "lastEventType" : "CERTIFICATE_UPDATE_ERROR",
    "displayName" : "...",
    "serialNumber" : "...",
    "imei" : "...",
    "imsi" : "...",
    "iccid" : "...",
    "modelId" : "...",
    "connectionIp" : "...",
    "biosVersion" : "...",
    "firmwareVersion" : "...",
    "osVersion" : "...",
    "jvmVersion" : "...",
    "osgiFrameworkVersion" : "...",
    "esfVersion" : "...",
    "applicationIdentifiers" : "...",
    "acceptEncoding" : "...",
    "gpsLatitude" : 12345.0,
    "gpsLongitude" : 12345.0,
    "customAttribute1" : "...",
    "customAttribute2" : "...",
    "customAttribute3" : "...",
    "customAttribute4" : "...",
    "customAttribute5" : "...",
    "optlock" : 12345,
    "uptime" : 12345,
    "modelName" : "...",
    "partNumber" : "...",
    "availableProcessors" : "...",
    "totalMemory" : "...",
    "os" : "...",
    "osArch" : "...",
    "jvmName" : "...",
    "jvmProfile" : "...",
    "osgiFramework" : "...",
    "connectionInterface" : "...",
    "gpsAltitude" : 12345.0,
    "deviceUserId" : 12345,
    "accountName" : "...",
    "signedCertificateId" : 12345,
    "mqttConnectionIp" : "...",
    "credentialsTight" : "INHERITED",
    "credentialsAllowChange" : true,
    "certificateCommonName" : "...",
    "brokerClusterId" : 12345
  } ]
}
                
              

GET /devices/sendRequest

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
 

  • $EDC: The $EDC prefix is used to mark all those topics that are used as "Control Topics" for the remote management. The prefix will distinguish control topics from data topics used in unsolicited reports and it marks the associated messages as transient, not stored in the historical data archive if one is present.
  • account_name: an unique identifier that represents a group of devices and users and maps to the name of the current Everyware Cloud account.
  • client_id: an unique identifier within an account that represents a single gateway device. This client_id maps to the Client Identifier (Client ID) as defined in the MQTT specifications. For a gateway, the MAC address of its primary network interface is generally used as the "client_id" of that gateway.
  • app_id: an identifier to denote an application running on the gateway device. We suggest to version the application identifier in order to allow multiple versions of the application to coexist, e.g. CONF-V1, CONF-V2, etc.
  • verb: An optional token identifying the action to be performed on the resource. Suggested values are: GET to read the resource, PUT to create or update the resource, DEL to delete the resource, EXEC to perform additional operations.
  • resource-id: An optional token identifying one or more resources owned by the application. Examples of resources are sensors, actuators, local files, or configuration options. Applications manage resources by being able to list them, read the latest value or update them to a new value. Each resource is identified by a resource_id, which can be a hierarchical topic. For example, "sensors/temp" or "sensors/hum" can act respectively as resource IDs for a temperature sensor and a humidity sensor.
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:
  • response.code: an error code for the remote operation. Valid codes are: 200, OK; 400, Bad Request; 404, Not Found; 500 Internal Error.
  • response.exception.message: Exception message, if any.
  • response.exception.stack: Remote exception stack trace, if any.

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/{accountName}/{clientId}/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.

Request Parameters
name type description default constraints
timeout query 0 required
topic query Target device and application. It is expressed with a structure like:
 $EDC / account_name / client_id / app_id / verb / resource - id
 
   
Response Body
media type data type description
application/json EdcResponsePayload (JSON) EdcResponsePayload response received from the remote device.
application/xml edcResponsePayload (XML)

Example

Request
GET /devices/sendRequest
Content-Type: application/xml
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "sentOn" : 12345,
  "position" : {
    "longitude" : 12345.0,
    "latitude" : 12345.0,
    "altitude" : 12345.0,
    "precision" : 12345.0,
    "heading" : 12345.0,
    "speed" : 12345.0,
    "timestamp" : 12345,
    "satellites" : 12345,
    "status" : 12345
  },
  "metrics" : {
    "metric" : [ {
      "name" : "...",
      "type" : "...",
      "value" : "..."
    }, {
      "name" : "...",
      "type" : "...",
      "value" : "..."
    } ]
  },
  "body" : "..."
}
                
              

POST /devices/sendRequest

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
 

  • $EDC: The $EDC prefix is used to mark all those topics that are used as "Control Topics" for the remote management. The prefix will distinguish control topics from data topics used in unsolicited reports and it marks the associated messages as transient, not stored in the historical data archive if one is present.
  • account_name: an unique identifier that represents a group of devices and users and maps to the name of the current Everyware Cloud account.
  • client_id: an unique identifier within an account that represents a single gateway device. This client_id maps to the Client Identifier (Client ID) as defined in the MQTT specifications. For a gateway, the MAC address of its primary network interface is generally used as the "client_id" of that gateway.
  • app_id: an identifier to denote an application running on the gateway device. We suggest to version the application identifier in order to allow multiple versions of the application to coexist, e.g. CONF-V1, CONF-V2, etc.
  • verb: An optional token identifying the action to be performed on the resource. Suggested values are: GET to read the resource, PUT to create or update the resource, DEL to delete the resource, EXEC to perform additional operations.
  • resource-id: An optional token identifying one or more resources owned by the application. Examples of resources are sensors, actuators, local files, or configuration options. Applications manage resources by being able to list them, read the latest value or update them to a new value. Each resource is identified by a resource_id, which can be a hierarchical topic. For example, "sensors/temp" or "sensors/hum" can act respectively as resource IDs for a temperature sensor and a humidity sensor.
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:
  • response.code: an error code for the remote operation. Valid codes are: 200, OK; 400, Bad Request; 404, Not Found; 500 Internal Error.
  • response.exception.message: Exception message, if any.
  • response.exception.stack: Remote exception stack trace, if any.

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

 curl --data '<message xmlns="http://eurotech.com/edc/2.0"><topic>$EDC/{accountName}/{clientId}/CONF-V1/GET/configurations</topic></message>' --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.

Request Parameters
name type description default constraints
timeout query 0 required
Request Body
media type data type
application/json EdcMessage (JSON)
application/xml edcMessage (XML)
Response Body
media type data type description
application/json EdcResponsePayload (JSON) EdcResponsePayload response received from the remote device.
application/xml edcResponsePayload (XML)

Example

Request
POST /devices/sendRequest
Content-Type: application/json
Accept: application/json

                
{
  "topic" : "...",
  "receivedOn" : 12345,
  "payload" : {
    "sentOn" : 12345,
    "position" : {
      "longitude" : 12345.0,
      "latitude" : 12345.0,
      "altitude" : 12345.0,
      "precision" : 12345.0,
      "heading" : 12345.0,
      "speed" : 12345.0,
      "timestamp" : 12345,
      "satellites" : 12345,
      "status" : 12345
    },
    "metrics" : {
      "metric" : [ { }, { } ]
    },
    "body" : "..."
  },
  "uuid" : "...",
  "edcTopic" : {
    "systemTopic" : true,
    "edcTopic" : true,
    "alertTopic" : true,
    "account" : "...",
    "asset" : "...",
    "semanticTopic" : "...",
    "leafName" : "...",
    "parentTopic" : "...",
    "grandParentTopic" : "...",
    "fullTopic" : "...",
    "topicParts" : [ "...", "..." ]
  }
}
                
              
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "sentOn" : 12345,
  "position" : {
    "longitude" : 12345.0,
    "latitude" : 12345.0,
    "altitude" : 12345.0,
    "precision" : 12345.0,
    "heading" : 12345.0,
    "speed" : 12345.0,
    "timestamp" : 12345,
    "satellites" : 12345,
    "status" : 12345
  },
  "metrics" : {
    "metric" : [ {
      "name" : "...",
      "type" : "...",
      "value" : "..."
    }, {
      "name" : "...",
      "type" : "...",
      "value" : "..."
    } ]
  },
  "body" : "..."
}
                
              

DELETE /devices/{clientId}

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

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

Example

Request
DELETE /devices/{clientId}
Content-Type: */*

                
...
                
              
Response
HTTP/1.1 204 No Content

              

GET /devices/{clientId}

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 -

Request Parameters
name type description
clientId path The client ID of the device requested.
Response Body
media type data type description
application/json Device (JSON) The list of requested devices.
application/xml device (XML)

Example

Request
GET /devices/{clientId}
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "ENABLED",
  "connectionStatus" : "CONNECTED",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "lastEventOn" : 12345,
  "lastEventType" : "CONF_COMP_UPDATED",
  "displayName" : "...",
  "serialNumber" : "...",
  "imei" : "...",
  "imsi" : "...",
  "iccid" : "...",
  "modelId" : "...",
  "connectionIp" : "...",
  "biosVersion" : "...",
  "firmwareVersion" : "...",
  "osVersion" : "...",
  "jvmVersion" : "...",
  "osgiFrameworkVersion" : "...",
  "esfVersion" : "...",
  "applicationIdentifiers" : "...",
  "acceptEncoding" : "...",
  "gpsLatitude" : 12345.0,
  "gpsLongitude" : 12345.0,
  "customAttribute1" : "...",
  "customAttribute2" : "...",
  "customAttribute3" : "...",
  "customAttribute4" : "...",
  "customAttribute5" : "...",
  "optlock" : 12345,
  "uptime" : 12345,
  "modelName" : "...",
  "partNumber" : "...",
  "availableProcessors" : "...",
  "totalMemory" : "...",
  "os" : "...",
  "osArch" : "...",
  "jvmName" : "...",
  "jvmProfile" : "...",
  "osgiFramework" : "...",
  "connectionInterface" : "...",
  "gpsAltitude" : 12345.0,
  "deviceUserId" : 12345,
  "accountName" : "...",
  "signedCertificateId" : 12345,
  "mqttConnectionIp" : "...",
  "credentialsTight" : "LOOSE",
  "credentialsAllowChange" : true,
  "certificateCommonName" : "...",
  "brokerClusterId" : 12345
}
                
              

PUT /devices/{clientId}

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

Request Parameters
name type description
clientId path The id of the Device to be updated.
Request Body
media type data type description
application/json Device (JSON) The modified Device whose attributes need to be updated.
application/xml device (XML)
Response Body
media type data type description
application/json Device (JSON) The updated Device.
application/xml device (XML)

Example

Request
PUT /devices/{clientId}
Content-Type: application/json
Accept: application/json

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "ENABLED",
  "connectionStatus" : "CONNECTED",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "lastEventOn" : 12345,
  "lastEventType" : "CERTIFICATE_UPDATED",
  "displayName" : "...",
  "serialNumber" : "...",
  "imei" : "...",
  "imsi" : "...",
  "iccid" : "...",
  "modelId" : "...",
  "connectionIp" : "...",
  "biosVersion" : "...",
  "firmwareVersion" : "...",
  "osVersion" : "...",
  "jvmVersion" : "...",
  "osgiFrameworkVersion" : "...",
  "esfVersion" : "...",
  "applicationIdentifiers" : "...",
  "acceptEncoding" : "...",
  "gpsLatitude" : 12345.0,
  "gpsLongitude" : 12345.0,
  "customAttribute1" : "...",
  "customAttribute2" : "...",
  "customAttribute3" : "...",
  "customAttribute4" : "...",
  "customAttribute5" : "...",
  "optlock" : 12345,
  "uptime" : 12345,
  "modelName" : "...",
  "partNumber" : "...",
  "availableProcessors" : "...",
  "totalMemory" : "...",
  "os" : "...",
  "osArch" : "...",
  "jvmName" : "...",
  "jvmProfile" : "...",
  "osgiFramework" : "...",
  "connectionInterface" : "...",
  "gpsAltitude" : 12345.0,
  "deviceUserId" : 12345,
  "accountName" : "...",
  "signedCertificateId" : 12345,
  "mqttConnectionIp" : "...",
  "credentialsTight" : "INHERITED",
  "credentialsAllowChange" : true,
  "certificateCommonName" : "...",
  "brokerClusterId" : 12345
}
                
              
Response
HTTP/1.1 204 No Content
Content-Type: application/json

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "ENABLED",
  "connectionStatus" : "MISSING",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "lastEventOn" : 12345,
  "lastEventType" : "APPS_UPDATED",
  "displayName" : "...",
  "serialNumber" : "...",
  "imei" : "...",
  "imsi" : "...",
  "iccid" : "...",
  "modelId" : "...",
  "connectionIp" : "...",
  "biosVersion" : "...",
  "firmwareVersion" : "...",
  "osVersion" : "...",
  "jvmVersion" : "...",
  "osgiFrameworkVersion" : "...",
  "esfVersion" : "...",
  "applicationIdentifiers" : "...",
  "acceptEncoding" : "...",
  "gpsLatitude" : 12345.0,
  "gpsLongitude" : 12345.0,
  "customAttribute1" : "...",
  "customAttribute2" : "...",
  "customAttribute3" : "...",
  "customAttribute4" : "...",
  "customAttribute5" : "...",
  "optlock" : 12345,
  "uptime" : 12345,
  "modelName" : "...",
  "partNumber" : "...",
  "availableProcessors" : "...",
  "totalMemory" : "...",
  "os" : "...",
  "osArch" : "...",
  "jvmName" : "...",
  "jvmProfile" : "...",
  "osgiFramework" : "...",
  "connectionInterface" : "...",
  "gpsAltitude" : 12345.0,
  "deviceUserId" : 12345,
  "accountName" : "...",
  "signedCertificateId" : 12345,
  "mqttConnectionIp" : "...",
  "credentialsTight" : "LOOSE",
  "credentialsAllowChange" : true,
  "certificateCommonName" : "...",
  "brokerClusterId" : 12345
}
                
              

POST /devices/{clientId}/command

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 -

Request Parameters
name type description
clientId path The client ID of the Device requested.
Request Body
media type data type
application/json DeviceCommandInput (JSON)
application/xml deviceCommandInput (XML)
Response Body
media type data type description
application/json DeviceCommandOutput (JSON) The command output.
application/xml deviceCommandOutput (XML)

Example

Request
POST /devices/{clientId}/command
Content-Type: application/json
Accept: application/json

                
{
  "command" : "...",
  "arguments" : [ "...", "..." ],
  "timeout" : 12345,
  "stdin" : "...",
  "environment" : [ "...", "..." ],
  "workingDir" : "...",
  "runAsync" : true,
  "password" : "..."
}
                
              
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "exitCode" : 12345,
  "timedout" : true,
  "stderr" : "...",
  "stdout" : "...",
  "exceptionMessage" : "...",
  "exceptionStack" : "..."
}
                
              

GET /devices/{clientId}/configurations

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 -

Request Parameters
name type description
clientId path The client ID of the device requested.
componentId query The PID (service's persistent identity) of the OSGi component requested.
Response Body
media type data type description
application/json DeviceConfiguration (JSON) The requested configuration.
application/xml deviceConfiguration (XML)

Example

Request
GET /devices/{clientId}/configurations
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "configuration" : [ {
    "pid" : "...",
    "OCD" : {
      "AD" : [ { }, { } ],
      "Icon" : [ { }, { } ],
      "any" : [ { }, { } ],
      "id" : "...",
      "name" : "...",
      "otherAttributes" : {
        "property1" : "...",
        "property2" : "..."
      },
      "description" : "..."
    },
    "properties" : {
      "property" : [ { }, { } ]
    }
  }, {
    "pid" : "...",
    "OCD" : {
      "AD" : [ { }, { } ],
      "Icon" : [ { }, { } ],
      "any" : [ { }, { } ],
      "id" : "...",
      "name" : "...",
      "otherAttributes" : {
        "property1" : "...",
        "property2" : "..."
      },
      "description" : "..."
    },
    "properties" : {
      "property" : [ { }, { } ]
    }
  } ]
}
                
              

POST /devices/{clientId}/configurations

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

Request Parameters
name type description
clientId path The client ID of the Device requested.
Request Body
media type data type description
application/xml deviceConfiguration (XML) The device configuration.

Example

Request
POST /devices/{clientId}/configurations
Content-Type: application/xml

                
<configurations xmlns="http://eurotech.com/esf/2.0">
  <configuration pid="...">
    <OCD description="..." id="..." name="..." xmlns="http://www.osgi.org/xmlns/metatype/v1.2.0">
      <AD/>
      <Icon/>
      <extension1 xmlns="">...</extension1>
      <extension2 xmlns="">...</extension2>
    </OCD>
    <properties>
      <property/>
    </properties>
  </configuration>
</configurations>

                
              
Response
HTTP/1.1 201 Created

              

POST /devices/{clientId}/disconnect

Disconnect the device with the specified clientId. A request is sent to the broker where the specified device is connected, then the broker will close the connection to that device.

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

Request Parameters
name type description
clientId path The client ID of the Device to disconnect

Example

Request
POST /devices/{clientId}/disconnect
Content-Type: */*

                
...
                
              
Response
HTTP/1.1 201 Created

              

GET /devices/{clientId}/events

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 -

Request Parameters
name type description default constraints
clientId path The client ID of the device requested.    
endDate query 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. 0  
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required
offset query Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 0 required
startDate query 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. 0  
Response Body
media type data type description
application/json DeviceEventsResult (JSON) The list of requested events.
application/xml deviceEventsResult (XML)

Example

Request
GET /devices/{clientId}/events
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "deviceEvent" : [ {
    "accountName" : "...",
    "clientId" : "...",
    "receivedOn" : 12345,
    "sentOn" : 12345,
    "eventType" : "DISCONNECTED",
    "eventMessage" : "...",
    "position" : {
      "longitude" : 12345.0,
      "latitude" : 12345.0,
      "altitude" : 12345.0,
      "precision" : 12345.0,
      "heading" : 12345.0,
      "speed" : 12345.0,
      "timestamp" : 12345,
      "satellites" : 12345,
      "status" : 12345
    },
    "accountId" : 12345
  }, {
    "accountName" : "...",
    "clientId" : "...",
    "receivedOn" : 12345,
    "sentOn" : 12345,
    "eventType" : "CONF_ROLLEDBACK",
    "eventMessage" : "...",
    "position" : {
      "longitude" : 12345.0,
      "latitude" : 12345.0,
      "altitude" : 12345.0,
      "precision" : 12345.0,
      "heading" : 12345.0,
      "speed" : 12345.0,
      "timestamp" : 12345,
      "satellites" : 12345,
      "status" : 12345
    },
    "accountId" : 12345
  } ]
}
                
              

GET /devices/{clientId}/packages

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 -

Request Parameters
name type description
clientId path The client ID of the Device requested.
Response Body
media type data type description
application/json XmlDeploymentPackages (JSON)
application/xml xmlDeploymentPackages (XML)

Example

Request
GET /devices/{clientId}/packages
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "package" : [ {
    "name" : "...",
    "version" : "...",
    "bundles" : [ {
      "name" : "...",
      "version" : "..."
    }, {
      "name" : "...",
      "version" : "..."
    } ]
  }, {
    "name" : "...",
    "version" : "...",
    "bundles" : [ {
      "name" : "...",
      "version" : "..."
    }, {
      "name" : "...",
      "version" : "..."
    } ]
  } ]
}
                
              

POST /devices/{clientId}/packages

Install a new deployment package on a device.

Example of query in CURL: curl --user 'username:password' -H 'Content-type: application/json' -d @/path/to/options.json -X POST https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/packages?packageUrl={packageUrl}

Request Parameters
name type description
clientId path The client ID of the Device requested.
packageUrl query Mandatory parameter with the URL of the package to install.
Request Body
media type data type description
application/json DevicePackageInstallOptions (JSON) (Optional) Additional parameters for installing the package. This is available for clients which support DEPLOY-V2.
application/xml devicePackageInstallOptions (XML)

Example

Request
POST /devices/{clientId}/packages
Content-Type: application/json

                
{
  "dpName" : "...",
  "dpVersion" : "...",
  "downloadProtocol" : "...",
  "downloadBlockSize" : 12345,
  "downloadBlockDelay" : 12345,
  "downloadBlockNotify" : 12345,
  "downloadTimeout" : 12345,
  "downloadResume" : true,
  "downloadForce" : true,
  "downloadUsername" : "...",
  "downloadPassword" : "...",
  "downloadHash" : "...",
  "install" : true,
  "installSystemUpdate" : true,
  "installVerifierURI" : "...",
  "installReboot" : true,
  "installRebootDelay" : 12345
}
                
              
Response
HTTP/1.1 201 Created

              

POST /devices/{clientId}/packages

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}

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

Example

Request
POST /devices/{clientId}/packages
Content-Type: */*

                
...
                
              
Response
HTTP/1.1 201 Created

              

POST /devices/{clientId}/rollback

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}

Request Parameters
name type description
clientId path The client ID of the Device requested.
snapshotId query

Example

Request
POST /devices/{clientId}/rollback
Content-Type: */*

                
...
                
              
Response
HTTP/1.1 201 Created

              

GET /devices/{clientId}/snapshots

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 -

Request Parameters
name type description
clientId path The client ID of the Device requested.
Response Body
media type data type description
application/json SnapshotIdsResult (JSON)
application/xml snapshotIdsResult (XML)

Example

Request
GET /devices/{clientId}/snapshots
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "snapshot" : [ 12345, 12345 ]
}
                
              

POST /devices/{clientId}/wakeupSMS

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

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

Example

Request
POST /devices/{clientId}/wakeupSMS
Content-Type: */*

                
...
                
              
Response
HTTP/1.1 201 Created

              

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

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}

Request Parameters
name type description
clientId path The client ID of the Device requested.
packageName path

Example

Request
DELETE /devices/{clientId}/packages/{packageName}
Content-Type: */*

                
...
                
              
Response
HTTP/1.1 204 No Content

              

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

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 -

Request Parameters
name type description
clientId path The client ID of the Device requested.
snapshotId path
Response Body
media type data type description
application/json DeviceConfiguration (JSON)
application/xml deviceConfiguration (XML)

Example

Request
GET /devices/{clientId}/snapshots/{snapshotId}
Content-Type: */*
Accept: application/json

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "configuration" : [ {
    "pid" : "...",
    "OCD" : {
      "AD" : [ { }, { } ],
      "Icon" : [ { }, { } ],
      "any" : [ { }, { } ],
      "id" : "...",
      "name" : "...",
      "otherAttributes" : {
        "property1" : "...",
        "property2" : "..."
      },
      "description" : "..."
    },
    "properties" : {
      "property" : [ { }, { } ]
    }
  }, {
    "pid" : "...",
    "OCD" : {
      "AD" : [ { }, { } ],
      "Icon" : [ { }, { } ],
      "any" : [ { }, { } ],
      "id" : "...",
      "name" : "...",
      "otherAttributes" : {
        "property1" : "...",
        "property2" : "..."
      },
      "description" : "..."
    },
    "properties" : {
      "property" : [ { }, { } ]
    }
  } ]
}