Was this helpful?

See all application entities

A group entity represents an application group of users. You can create, retrieve, update, delete, and query group entities. See User entity properties 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 POST "https://api.usergrid.com/your-org/your-app/groups" '{ request body }'

Use the POST method to create a new group. Groups use paths to indicate their unique names. This allows you to create group hierarchies by using slashes. For this reason, you need to specify a path property for a new group.

Request URI

POST /{org_id}/{app_id}/groups

Parameters

Parameter Description
uuid | org_id Organization UUID or organization name
uuid | app_id Application UUID or application name
request body

One or more sets of group properties, of which path is mandatory and must be unique. The path value may include forward slashes to denote hierarchical relationships.

{
    "path" : "somegroup/somesubgroup",
    "title" : "Some SubGroup"
}

Example

Note: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.

Request

curl -X POST "https://api.usergrid.com/my-org/my-app/groups" -d '{"path":"mynewgroup"}'

Response

{
    "action": "post",
    "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
    "params": {},
    "path": "/groups",
    "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups",
    "entities": [{
        "uuid": "a668717b-67cb-11e1-8223-12313d14bde7",
        "type": "group",
        "created": 1331066016571,
        "modified": 1331066016571,
        "metadata": {
            "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7",
            "sets": {
                "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/rolenames",
                "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/permissions"
            },
            "collections": {
                "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/activities",
                "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/feed",
                "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/roles",
                "users": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users"
            }
        },
        "path": "mynewgroup"
    }],
    "timestamp": 1331066016563,
    "duration": 35,
    "organization": "my-org",
    "applicationName": "my-app"
}

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

Synchronous

-(ApigeeClientResponse *)createGroup:(NSString *)groupPath
                          groupTitle:(NSString *)groupTitle;

Asynchronous

-(ApigeeClientResponse *)createGroup:(NSString *)groupPath
                          groupTitle:(NSString *)groupTitle
                   completionHandler:(ApigeeDataClientCompletionHandler)completionHandler;

Parameters

Parameter Description
completionHandler A handler to receive the response from an asynchronous call.
groupPath A path, optionally showing hierarchical relationships. This must be unique in your data store.
groupTitle A friendly name for the group.

Example

This example uses the iOS SDK.

// Values with which to create the new group.
NSString *path = @"superusers/do";
NSString *title = @"SuperUsers Do";

// Create a query instance specifying the path that
// was requested for the new group.
ApigeeQuery *query = ;

// Find out if a group with this path already exists.
[[apigeeClient dataClient] getEntities:@"groups" query:query
                     completionHandler:^(ApigeeClientResponse *result)
{
    if ([result completedSuccessfully]) {
        if ([result.response[@"entities"] count] > 0)
        {
            // If there's a group entity with that path value,
            // ask the user to chose another path value. 
        } else {
            // Call an SDK method to create the group with the
            // name and path values given in the UI.
            [[apigeeClient dataClient] createGroup:path
                                        groupTitle:name
                                 completionHandler:^(ApigeeClientResponse *response)
            {
                if ([response completedSuccessfully])
                {
                    // Do something when the request succeeds.
                } else {
                    // Display or log an error.
                }
            }];
        }
    } else {
        // Display or log an error message.
    }
}];

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

Synchronous

public ApiResponse createGroup(String groupPath)
public ApiResponse createGroup(String groupPath, 
                               String groupTitle)
public ApiResponse createGroup(String groupPath, 
                               String groupTitle, 
                               String groupName)

Asynchronous

public void createGroupAsync(String groupPath,
                             final ApiResponseCallback callback)
public void createGroupAsync(final String groupPath,
			     final String groupTitle, 
			     final ApiResponseCallback callback)

Parameters

Parameter Description
callback A handler to receive the response from an asynchronous call.
groupPath A path, optionally showing hierarchical relationships. This must be unique in your data store.
groupTitle A friendly name for the group.

Example

In this example, the code to create a group is within code to find out if the group requested group path already exists for a group. This is like checking to see if a requested username exists before using that value for a new user. This example uses the Android SDK.

// A query statement with which to check for an existing group
// with the same path (which must be unique).
String queryText = "path='mynewgroup'";

// Call the DataClient method to find out if there's already
// a group with the path value the user entered. If not, add the
// group. Some callback methods are omitted for brevity.
dataClient.queryGroupsAsync(queryText, new QueryResultsCallback(){

    // Called to receive the query response.
    @Override
    public void onResponse(Query query) {
        ApiResponse response = query.getResponse();
        List<entity> groups = response.getEntities();

        if (groups.size() > 0){
            // There's a group with this path, so display
            // or log a message.
        } else {
            // Create a new group with data entered. 
            dataClient.createGroupAsync(groupPath, 
                    groupTitle, new ApiResponseCallback(){
                    
                // Called to receive the response from the
                // attempt to create a group.
                @Override
                public void onResponse(ApiResponse response) {
                    // Do something after successfully
                    // creating the group.
                }
            });
        }
    }
});

These are Usergrid.Client methods for adding groups to your data store. (Usergrid is the open source project on which these features are based.)

Synchronous

apigeeClient.createGroup(options, callback)

Parameters

Parameter Description
callback A handler to receive the response from an asynchronous call.
options A JSON object containing values for the group's properties.

Example

This example uses the JavaScript SDK.

// Bundle values in a JSON object.
var options = {
    "path" : "superusers/do",
    "title" : "SuperUsers Do"
}

// Call an SDK method to create the group with the collected
// data.
apigeeClient.createGroup(options, function (error, response) {
    // If the attempt fails, display an error message.
    if (error) {
        // Display or log a message.
    } else {
        // Do something now that the request has succeeded.
    }
});    

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
app['groups'].post path: 'mynewgroup'

The example assumes use of the Node.js module.

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

 

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.