Manage User Devices

You can easily create, update, read, and delete Devices for new or existing Users in our system. That is, any call to CRUD a Device requires an associated User (i.e. a User ID). If that User can't be located, a new one will be created.

The only required attributes are unique_identifier for a Device and name and email for a User. 

XML is default; thus, if you'd like to use JSON, please use HTTP headers Accept and Content-Type.

URLs:

For example, if using JSON when creating a new User and new Device, then the resulting document would look something like:

{
 "device":
  {
   "unique_identifier":"qwerty1234555", "description":"My device test one", "platform":"iOS"
  }, 
 "user":
  {
   "name":"User One 5", "email":"user.one.+@mailinator.com"
  }
}

As an example of creating a Device along with a User, here is a Node.js call (written in CoffeeScript) using a RESTful POST:

client = require('restler')

options = { headers: {'X-Token':'ZSUV222zdse3J9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } }

newDeviceNewUser = { device: {unique_identifier:'qwerty1234555', description:'My device test one', platform: 'iOS'}, 
  user:  {name: 'User One 5', email: 'user.one.+@mailinator.com'}}

createOptions = options
createOptions['data'] = JSON.stringify(newDeviceNewUser)
client.post("https://cirrus.app47.com/api/devices", createOptions).on('2XX', (data, response) -> 
	json = JSON.parse(JSON.stringify(data)))

The response from a call like this will be something along the lines of:

{
 "_id":"4f3446ac6f4caf264400007f",
 "account_id":"4d5303e8b8a46d1746000002",
 "devices":[ 
    {"_id":"4f3446ac6f4caf2644000080",
     "description":"My device test one",
     "platform":"iOS",
     "state":"pending",
     "token":"JwdYApTWkrF-WeyUMr8UiA",
     "unique_identifier":"qwerty1234555"
     }],
     "email":"user.one.+@mailinator.com",
     "group_ids":[],
     "name":"User One 5",
     "passphrases":[
       {"_id":"4f3446ac6f4caf2644000081",
         "creation_date":"2012-02-09T17:20:28-05:00",
         "passphrase":"bikidatedu",
         "used":false,
         "valid_duration_hrs":48
        }]
}

Take note—the Device has an ID (in this case it's 4f3446ac6f4caf2644000080). Note too, that this User's Device is in needs approval (which an admin for the account can facilitate). If you wish to give this User approval via the API, include the attribute auto_approved and set it to true. 

Also, Users can be associated with Groups (either new or existing). For more information, please see the wiki for details on Users and Groups. 

And to update the same Device, use an HTTP PUT.

Note: the Device ID in this case was obtained from an earlier call to create the Device. The Device ID is accordingly placed in the URL (i.e. https://cirrus.app47.com/api/devices/080asc23oiuoiuA333)

updateOptions = { headers: {'X-Token':'ZSUV222sa3zJ9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } }
updateOptions['data'] = JSON.stringify( { device: { description:'My device test one..updated'}} )
client.put("https://cirrus.app47.com/api/devices/" + deviceId, updateOptions)

You can read or GET a Device by its ID as well:

client.get("https://cirrus.app47.com/api/devices/" + deviceId, options).on('2XX', (data, response) -> 
  console.log JSON.parse(JSON.stringify(data)))

In the code above, deviceId is a valid Device ID – the response will look something like:

{
  "_id":"4f344a456f4caf2644000086",
  "description":"My device test one..updated",
  "platform":"iOS",
  "state":"pending",
  "token":"6retMWMSpUn__B_nasrL4A",
  "unique_identifier":"qwerty1234555"
}

You can read or GET a Device and its associated User the ID:

client.get("https://cirrus.app47.com/api/devices/" + deviceId+"?show_user=true", options).on('2XX', (data, response) -> 
  console.log JSON.parse(JSON.stringify(data)))

In the code above, deviceId is a valid Device ID – the response will look something like:

   {"user":
     {"_id":"54189340530a693f430000c0",
      "account_id":"54189340530a693f4300009e",
      "active":true,
      "allowed_app_ids":[],
      "app_store_analytics":{
        "_id":"54189340530a693f430000c1",
        "installed_store_count":0,
        "last_sign_in":null,
        "sign_in_count":0,
        "store_installed":false,
        "updated_at":null
        },
       "auto_approved":true,
       "created_at":"2014-09-16T15:45:04-04:00",
       "default_passphrase_expiration":48}
   ,"device":{
    "_id":"54189340530a693f430000c2",
    "appstore_last_sign_in":null,
    "appstore_sign_in_count":0,
    "description":"description",
    "model":"iPad3,3",
    "os_version":null,
    "platform":"iOS",
    "state":"approved",
    "token":"1",
    "unique_identifier":"uuid4",
    "updated_at":null,
    "user_agent":"Unknown"}
 }

Finally, you can also remove a Device – just issue an HTTP DELETE and include the Device's ID in the URL (just like with GETs and PUTs):

client.del("https://cirrus.app47.com/api/devices/" + deviceId, options).on('2XX', (data, response) -> console.log "Device deleted")