Managing Groups

You can easily create, update, read, and delete Groups (that is, named collections of Users) in our system. Notice that you can add Users to Groups via the Users API.

The only required attribute is a Group's name. You can optionally specify a list of App ID's for which this group has rights to, and a description can also be provided for a Group.

You may specify JSON or XML as an exchange format. XML is default; thus, if you'd like to use JSON, please use HTTP headers Accept and Content-Type.

Required parameter: name Optional parameters: description, app_ids

URLs:

For example, if using JSON when creating a Group, then the resulting document would look something like:

{
 _id: '4f357c5e6f4caf3ef1000003',
 account_id: '4d5303e8b8a46d1746000002',
 app_ids: [ '4e552727a2f8fd000100006f' ],
 name: 'API Demo Testing group updated',
 user_ids: [] 
}

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

client = require('restler')
options = { headers: {'X-Token':'ZSUV222zJ9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } }
createOptions = options
createOptions['data'] = JSON.stringify({group:{ name: "API Demo Testing Group"}})
client.post("http://cirrus.app47.com/api/groups", createOptions).on('2XX', (data, response) -> 
  json = JSON.parse(JSON.stringify(data))
  console.log "group id is "  + json['_id'])

And to update the same Group, use an HTTP PUT. Note, the Group ID in this case was obtained from an earlier call to create the Group. The Group ID is accordingly placed in the URL (i.e. https://cirrus.app47.com/api/groups/080asc23oiuoiuA333)

updateOptions = { headers: {'X-Token':'ZSUV222zJ9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } }
updateOptions['data'] = JSON.stringify({group:{ name: "API Demo Testing group updated", app_ids: ['4e552727a2f8fd000100006f'] }})
client.put("http://cirrus.app47.com/api/groups/" + groupId, updateOptions)

You can read or GET an Group by it's ID as well:

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

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

<code>
{
 _id: '4f357c5e6f4caf3ef1000003',
 account_id: '4d5303e8b8a46d1746000002',
 app_ids: [ '4e552727a2f8fd000100006f' ],
 name: 'API Demo Testing group updated',
 user_ids: [] 
}

</code>

You can read or GET via searching the name.

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

In the code above, name is a group name in your account – the response will look something like:

[{
 _id: '4f357c5e6f4caf3ef1000003',
 account_id: '4d5303e8b8a46d1746000002',
 app_ids: [ '4e552727a2f8fd000100006f' ],
 name: 'API Demo Testing group updated',
 user_ids: [] 
}]

If no groups matching you search term are found, an empty array will be returned.

[]

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

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