REST Interface

Device Cloud provides a RESTful interface to enable you to write applications that send TR50 commands.

You use the URL you were given when you received your Device Cloud account as the endpoint for API calls. The URL is specific to your geographic region. For North America, the URL is https://launchpad-us.devicewise.com.

The application uses the Auth API to retrieve a token to use in subsequent API calls. The request header for the auth request must contain an HTTP Basic Authentication entry with a valid Device Cloud user name and password.

curl -X POST \
  https://launchpad-us.devicewise.com/rest/hdc/auth/v1/token \
  -H 'authorization: Basic YXVzZXJAYWNvbXBhbnkuY29tOnBhc3N3b3Jk=' 

By default, the token expires in 24 hours (the maximum expiry time). Optionally, you can specify the ttl body parameter to specify a shorter expiry time in seconds.

Applications call the POST method for the TR50 API to send TR50 messages. The header must specify the following:

• Authorization: Bearer token, where token is the token you retrieved using the Auth API

• Content-type: application/json

The format of the body parameter is the TR50 message format specified in a requests object as shown in the following example:

{
"requests": {
  "1" : {
    "command" : "commandName",
    "params" : {
      commandParameters
    }
  }
}

The following shows an example cURL request:

curl -X POST \
  https://launchpad-us.devicewise.com/rest/hdc/tr50/v1/request \
  -H 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTA2Njk4MTgsIm5iZiI6MTUxMDY2NjIxOCwiZXhwIjoxNTEwNzU2MjE4LCJqdGkiOiJlZWJmZmI4MC1jNzZjLTRlMmMtOTMyOC00MTg4ZWQ0NzkxZjMiLCJpc3MiOiJ3d3cuaGRjc3RnLm5ldCIsInN1YiI6Imp1bGlhLmtlZmZlckB3aW5kcml2ZXIuY29tIiwidGVsaXQiOiI1YTBhZmRmOTY0NzA0Mzc5NDYzMzQ3MzIiLCJ0aWQiOiJXUlBVQlMiLCJwZXJtaXNzaW9uIjp7ImF1dGgiOnRydWUsImRldm1nbXQiOnRydWUsImV4YW1wbGUiOnRydWUsImxhdW5jaHBhZCI6dHJ1ZSwib3RhIjp0cnVlLCJyZW1vdGUtYWNjZXNzIjp0cnVlLCJzZG8iOnRydWUsInRyNTAiOnRydWV9fQ.IGngxsGz_H-QY0-3vbn610lndKk9PDq7IZAVJMui74cWZJ_navnIZH2T1AyirP9YQwqoqPy1Aw3xFR7q4zM6oLXP5-h-Gg28xZhsnBsaEGK9OYmPlu8GoXX4B1l_jjTztPArdVoWgiaBvXdraOKGDkmw98__nhqeNSbb2AwhAbfLbBjVKQK896Xb7WOZ5jrlNTIlewysU5vk4f4qJ4JOJDfjiDANgJ9DxcslxaH7O-Jf_q62amguGmbRtys12KR4SUs4G1H8pkbymipa1lMdEb_0ncnyKc8ym69YgPqTgJTgB2Y2T30tUIoYGUh_O_7LPbjTWEvwtrjo8-khuXycTg' \
  -H 'content-type: application/json' \
  -d '{
    "requests": {
    "1": {
        "command": "thing.attr.get",
        "params": {
            "thingKey": "ee2ba9c1-fc44-47e2-91cb-f22e87671253-device-manager",
            "key": "os_name"
        }
    }
}
}'

The response is as follows:

{
    "1": {
        "success": true,
        "params": {
            "ts": "2017-11-13T15:56:01.137Z",
            "value": "ubuntu"
        }
    }
}

For details about the TR50 message format, see TR50 Message Format.