—Rate this article—
 

Retrieving groups

Retrieving group data

You can retrieve data about groups through cURL or one of the SDKs. Each provides a way to filter the list of groups by data associated with the group, such as title or path, or other properties in the group entity.

See Default Data Entity Types for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application.

Request Syntax

curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mynewgroup"

Use the GET method to retrieve group data.

Request URI

GET /<org_id | uuid>/<app_id | uuid>/groups</groupPath | uuid> | <?ql=query_string>

Parameters

Parameter Description
org_id | uuid Organization UUID or organization name
app_id | uuid Application UUID or application name
groupPath | uuid Group UUID or group path, which must be unique.
query_string A data store query. For more on queries, see Data queries.

Request

# Get a group by the group path, "employees/managers".
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/employees/managers"

# Get a group by UUID.
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/a407b1e7-58e8-11e1-ac46-22000a1c5a67e"

# Get group data filtering by their title.
curl -X GET "https://api.usergrid.com/my-org/my-app/groups?ql=select%20*%20where%20title%3D'Management%20Employees'"

Response

The following is an example of JSON returned by a query for a single group.

{
    "action" : "get",
    "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20",
    "params" : { },
    "path" : "/groups",
    "uri" : "https://api.usergrid.com/steventraut/mynewapp/groups",
    "entities" : [ {
        "uuid" : "5005a0fa-6916-11e3-9c1b-b77ec8addc0d",
        "type" : "group",
        "created" : 1387503030399,
        "modified" : 1387503030399,
        "path" : "managers",
        "metadata" : {
            "path" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d",
            "sets" : {
                "rolenames" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/roles",
                "permissions" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/permissions"
            },
            "collections" : {
                "activities" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/activities",
                "feed" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/feed",
                "roles" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/roles",
                "users" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/users"
            }
        },
        "title" : "Management Employees"
    } ],
    "timestamp" : 1391020491701,
    "duration" : 15,
    "organization" : "my-org",
    "applicationName" : "my-app"
}

To retrieve group data, use method for retrieving entities, specifying "groups" as the collection type. For more information, see Retrieving Data Entities.

Example

This example uses the iOS SDK.

The following example retrieves groups from the data store, filtering the returned data by city.

NSMutableArray* groups;

// Create an ApigeeQuery instance to capture query params.
ApigeeQuery *query = [ [ApigeeQuery alloc] init];

// Add a query requirement to narrow the request. This asks for groups
// whose title value is "Management Employees".
[query addRequirement:[NSString stringWithFormat:@"title='%@'", @"Management Employees"]];

// Get groups from the application with an SDK method. To 
// retrieve all groups, regardless of title, you could pass nil for 
// the query parameter.
ApigeeClientResponse* result =
    [[apigeeClient dataClient] getEntities:@"groups" query:query];

// Get the group data as an array.
groups = result.response[@"entities"];
    
// Do something with the data.

These are DataClient methods for adding groups to your data store.

Asynchronous

public void queryGroupsAsync(QueryResultsCallback callback)
public void queryGroupsAsync(String ql, QueryResultsCallback callback)

Synchronous

public Query queryGroups(String ql)

Parameters

Parameter Description
callback A handler to receive the response from an asynchronous call.
ql A string specifying query parameters. See Querying your data for more information about queries.

This example uses the Android SDK.

Example

// Call a DataClient method to retrieve the group data
// asynchronously. Handle the result with methods of the 
// callback object created here. Some of the callback's
// methods are omitted for brevity.
dataClient.queryGroupsAsync(new QueryResultsCallback() {

    // Handle the result of the query here.
    @Override
    public void onResponse(Query query) {
    
    	ApiResponse response = query.getResponse();
    	
    	// Get the list of groups from the query response.
    	List<Entity> groups = response.getEntities();
    	if (groups.size() > 0)
    	{
    		// Loop through the groups data, doing something
            // interesting for each.
    	} else {
    		// Do something if there aren't any groups.
    	}
    }
});

This is the Usergrid.Collection method for getting group data from the data store. This method assumes a Collection instance that has been created with a Groups collection type. (Usergrid is the open source project on which these features are based.)

Asynchronous

collection.fetch (callback)

Parameters

Part Description
callback A handler to receive the response from an asynchronous call.
collection A Usergrid.Collection instance.

Example

This example uses the JavaScript SDK.

// A local collection variable to hold the group data.
// apigeeClient is an instance of Usergrid.Client.
var groups = new Apigee.Collection({
    "client": apigeeClient,
    "type": "groups"
});

// Attempt to get the group data.
groups.fetch(
    // Called if the fetch attempt succeeded.
    function () {

        if (groups.hasNextEntity()) {
            while (groups.hasNextEntity()) {
                // Do something interesting with each
                // group returned.
            }
        } else {
            // Handle the case when no groups are
            // returned.
        }
    },
    function () {
        // Handle the error case.
    }
);

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
group = app['mynewgroup'].entity

The example assumes use of the Node.js module.

var options = {
    method:'GET',
    endpoint:'groups/mynewgroup'
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success - data will contain raw results from API call
    }
});

 

Retrieving a group's users

Use the GET method to retrieve all the users in a group.

Request URI

GET /{org_id}/{app_id}/groups/{uuid|groupname}/users

Parameters

Parameter Description
arg uuid|string org_id Organization UUID or organization name
arg uuid|string app_id Application UUID or application name
arg uuid|string groupname UUID or name of the group

Example - Request

curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mygroup/users"

The example assumes use of the JavaScript (HTML5) SDK.

var options = {
    method:'GET',
    endpoint:'groups/mygroup/users'
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success - data will contain raw results from API call
    }
});

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
activities = app['groups/mygroup/users'].collection

The example assumes use of the Node.js module.

var options = {
    method:'GET',
    endpoint:'groups/mygroup/users'
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success - data will contain raw results from API call
    }
});

Example - Response

{
  "action" : "get",
  "application" : "e7127751-6985-11e2-8078-02e81aeb2129",
  "params" : { },
  "path" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users",
  "uri" : "http://api.usergrid.com/myorg/sandbox/groups/d20976ff-802f-11e2-b690-02e81ae61238/users",
  "entities" : [ {
    "uuid" : "cd789b00-698b-11e2-a6e3-02e81ae236e9",
    "type" : "user",
    "name" : "barney",
    "created" : 1359405994314,
    "modified" : 1361894320470,
    "activated" : true,
    "email" : "barney@apigee.com",
    "metadata" : {
      "path" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9",
      "sets" : {
        "rolenames" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/rolenames",
        "permissions" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/permissions"
      },
      "collections" : {
        "activities" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/activities",
        "devices" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/devices",
        "feed" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/feed",
        "groups" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/groups",
        "roles" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/roles",
        "following" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/following",
        "followers" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/followers"
      }
    },
    "name" : "barney",
    "picture" : "http://www.gravatar.com/avatar/00767101f6b4f2cf5d02ed510dbcf0b4",
    "test" : "fred",
    "username" : "barney"
  } ],
  "timestamp" : 1361903248398,
  "duration" : 24,
  "organization" : "myorg",
  "applicationName" : "sandbox"
}

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)