Was this helpful?

See all application entities

You can retrieve data about users through cURL or one of the SDKs. Each provides a way to filter the list of users by data associated with the user, such as username or UUID, or other properties in the user entity.

See User entity properties for a list of the system-defined  properties for user entities. In addition, you can create user properties specific to your application.

Request Syntax

curl -X GET "https://api.usergrid.com/your-org/your-app/users"

Use the GET method to retrieve user data.

Request URI

GET /<org_id>/<app_id>/users</uuid | username | email_address | ?ql=query_string>

Parameters

Parameter Description
uuid | org_id Organization UUID or organization name
uuid | app_id Application UUID or application name
uuid | uuid | username | email_address User UUID, username, or email address. The alias /users/me can be used in place of the current user’s uuid, username, or email address. Note: The /users/me endpoint is accessible only if you provide an access token with the request (see Authenticating users and application clients). If you make an anonymous ("guest") call, the system will not be able to determine which user to return as /users/me.

Note: The username can contain any combination of characters, including those that represent letters, numbers, and symbols.

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

# Get a user by username.
curl -X GET "https://api.usergrid.com/my-org/my-app/users/jane.doe"

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

# Get a user by email.
curl -X GET "https://api.usergrid.com/my-org/my-app/users/jane.doe@gmail.com"

# Get user data filtering by their city property value.
curl -X GET "https://api.usergrid.com/my-org/my-app/users?ql=select%20*%20where%20adr.city%3D'Chicago'"

Response

{
    "action" : "get",
    "application" : "1c8f60e4-da67-11e0-b93d-12313f0204bb8",
    "params" : {
        "_": [
            "1315524419746"
        ]
    },
    "path" : "https://api.usergrid.com/12313f0204bb-1c8f60e4-da67-11e0-b93d/1c8f60e4-da67-11e0-b93d-12313f0204bb/users",
    "uri" : "https://api.usergrid.com/005056c00008-4353136f-e978-11e0-8264/4353136f-e978-11e0-8264-005056c00008/users",
    "entities" : [ {
        "uuid" : "78c54a82-da71-11e0-b93d-12313f0204b",
        "type" : "user",
        "created" : 1315524171347008,
        "modified" : 1315524171347008,
        "activated" : true,
        "email" : "jane.doe@gmail.com",
        "metadata" : {
            "path" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb",
            "sets" : {
                "rolenames" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/rolenames",
                "permissions" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/permissions"
            },
            "collections" : {
                "activities" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/activities",
                "devices" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/devices",
                "feed" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/feed",
                "groups" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/groups",
                "roles" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/roles",
                "following" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/following",
                "followers" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/followers"
            }
        },
        "username" : "jane.doe"
    }
    ... Additional entities here if data for multiple users was returned...
    ],
    "timestamp" : 1315524421071,
    "duration" : 107,
    "organization" : "my-org",
    "applicationName": "my-app"
}

These are ApigeeDataClient methods for retrieving user data from your data store.

Asynchronous

-(ApigeeClientResponse *)getUsers:(ApigeeQuery *)query
                completionHandler:(ApigeeDataClientCompletionHandler)completionHandler;

Synchronous

-(ApigeeClientResponse *)getUsers:(ApigeeQuery *)query;

Parameters

Parameter Description
completionHandler A handler to receive the response from an asynchronous call.
email The user's email address. This must be unique in your data store.
name A friendly name for the user.
password A password with which the user can log in.
username The username value with which the user will log in. This must be unique in your data store. The string may only include A-Z, a-z, 0-9, dot, underscore and dash. It must be between 4 and 15 characters.

This example uses the iOS SDK.

Example

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

NSMutableArray* users;

// Create an ApigeeQuery instance to capture query params.
ApigeeQuery *query = ;

// Get users from the application with an async SDK method. To 
// retrieve all users, regardless of city, you could pass nil for 
// the query parameter.
[[apigeeClient dataClient] getUsers:
            query completionHandler:^(ApigeeClientResponse *result)
{
     // If the request was successful, assign the resulting list
     // to an array that will be used to display in the UI.
     if ([result completedSuccessfully]) {
         self.users = result.response[@"entities"];
     } else {
         self.users = [[NSMutableArray alloc] init];
     }
}];

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

Asynchronous

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

Synchronous

public Query queryUsers()
public Query queryUsers(String ql)
public Query queryUsersWithinLocation(float distance, float latitude,
            float longitude, String ql)

Parameters

Parameter Description
callback A handler to receive the response from an asynchronous call.
distance Distance from the location specified by the latitude and longitude.
latitude Latitude of the location queried about.
longitude Longitude of the location queried about.
ql A string specifying query parameters. See Querying your data for more information about queries.

This example uses the Android SDK.

Example

// Create a query string that narrows the results to 
// the users you want -- here, those whose city value is "Chicago".
String ql = "adr.city='Chicago'";

// Call a data client method to retrieve the user data
// asynchronously. Handle the result with methods of the
// callback object created here.
dataClient.queryUsersAsync(ql, new QueryResultsCallback() {

    @Override
    public void onException(Exception e) {
        // Log an error.
    }

    // Handle the result of the query here.
    @Override
    public void onResponse(Query query) {
        if (query != null) {
            ApiResponse response = query.getResponse();
            if (response != null) {
                // Get the list of users from the query response.
                List users = response.getEntities();

                // Do something with the user data here, such 
                // as bind it to some user interface.

            } else {
                // Display and/or log an error.
            }
        }
    }

    @Override
    public void onQueryResults(Query query) {
        // This method is currently not implemented.
    }
});

This is the Usergrid.Collection method for getting user data from the data store. This method assumes a Collection instance that has been created with a "users" 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.

// Create a collection instance to keep the users in. 
// apigeeClient is an instance of Apigee.Client. This 
// expression uses a query to narrow the results to 
// only those users whose city value is "Chicago".
// To get all users regardless of city, you'd not 
// include a qs property when creating the collection.
var users = new Apigee.Collection({
    "client":apigeeClient,
    "type":"users",
    "qs": {
        "ql":"adr.city = 'Chicago'"
    }
});

// Fetch the users from the database.
users.fetch(
    // Called if the fetch succeeded.
    function () {
        if (users.hasNextEntity()){
            // Do something with the received data.
        } else {
            // Do something if there aren't any users in that city.
        }
    },
    // Called if the attempt to get users failed.
    function () {
        client.logError({tag:"getUsers", 
            logMessage:"Unable to retrieve users."})
    }
);

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_user username: 'john.doe', name: 'John Doe', email: 'john.doe@gmail.com'
john_doe = result.entity

The example assumes use of the Node.js module.

var options = {
    method:'POST',
    endpoint:'users',
    body:{ username:'john.doe', name:'John Doe', email:'john.doe@gmail.com' }
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call        
    }
});

 

Add new comment

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.