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 -

Example

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

                
...
                
              

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" : "BUNDLE_STOPPED",
    "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
  }, {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "ENABLED",
    "connectionStatus" : "MISSING",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "lastEventOn" : 12345,
    "lastEventType" : "PROVISIONING_FAILED",
    "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

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

Example

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" : "..."
}
                
              

HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "DISABLED",
  "connectionStatus" : "MISSING",
  "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" : "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.

Example

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

                
...
                
              

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

Example

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

                
...
                
              

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

                
{
  "limitExceeded" : true,
  "device" : [ {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "ENABLED",
    "connectionStatus" : "MISSING",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "lastEventOn" : 12345,
    "lastEventType" : "DC",
    "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
  }, {
    "accountId" : 12345,
    "id" : "...",
    "clientId" : "...",
    "status" : "DISABLED",
    "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" : "STRICT",
    "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.

 $EDC/account_name/client_id/app_id/#
 

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.

 $EDC / account_name / requester.client.id / app_id / REPLY / request.id
 

• 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'
 

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

Example

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

                
...
                
              

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.

 $EDC/account_name/client_id/app_id/#
 

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.

 $EDC / account_name / requester.client.id / app_id / REPLY / request.id
 

• 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'
 

Example

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

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.

Example

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

                
...
                
              

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 -

Example

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

                
...
                
              

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

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "DISABLED",
  "connectionStatus" : "DISCONNECTED",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "lastEventOn" : 12345,
  "lastEventType" : "MISSING",
  "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
}
                
              

PUT /devices/{clientId}

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

Example

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

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "ENABLED",
  "connectionStatus" : "DISCONNECTED",
  "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
}
                
              

HTTP/1.1 204 No Content
Content-Type: application/json

                
{
  "accountId" : 12345,
  "id" : "...",
  "clientId" : "...",
  "status" : "DISABLED",
  "connectionStatus" : "DISCONNECTED",
  "createdOn" : 12345,
  "createdBy" : 12345,
  "lastEventOn" : 12345,
  "lastEventType" : "CONF_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 -

Example

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

                
{
  "command" : "...",
  "arguments" : [ "...", "..." ],
  "timeout" : 12345,
  "stdin" : "...",
  "environment" : [ "...", "..." ],
  "workingDir" : "...",
  "runAsync" : true,
  "password" : "..."
}
                
              

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 -

Example

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

                
...
                
              

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

Example

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>

                
              

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

Example

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

                
...
                
              

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 -

Example

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

                
...
                
              

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

                
{
  "limitExceeded" : true,
  "deviceEvent" : [ {
    "accountName" : "...",
    "clientId" : "...",
    "receivedOn" : 12345,
    "sentOn" : 12345,
    "eventType" : "CONNECTED",
    "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" : "CERTIFICATE_UPDATE_ERROR",
    "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 -

Example

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

                
...
                
              

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}

Example

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
}
                
              

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}

Example

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

                
...
                
              

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}

Example

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

                
...
                
              

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 -

Example

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

                
...
                
              

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

Example

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

                
...
                
              

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}

Example

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

                
...
                
              

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 -

Example

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

                
...
                
              

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