Retrieving Data Entities

This article describes how to retrieve entities from your account.

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.

Retrieving an entity

cURL

Request Syntax

curl -X GET https://<baas_host_name>/<org>/<app>/<collection>/<entity>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
collection Collection UUID or collection name
entity Entity UUID or entity name

Example Request/Response

Request:

Retrieve by UUID:

curl -X GET "https://<baas_host_name>/your-org/your-app/items/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"

Retrieve by 'name' property:

curl -X GET "https://<baas_host_name>/your-org/your-app/items/milk"

Response:

{
        "action" : "get",
        "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://api.usergrid.com/amuramoto/sandbox/items",
        "entities" : [ {
                "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
                "type" : "item",
                "name" : "milk",
                "created" : 1378405020796,
                "modified" : 1378405020796,
                "metadata" : {
                          "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
                },
                "name" : "milk",
                "price" : "3.25"
        } ],
        "timestamp" : 1378405025763,
        "duration" : 31,
        "organization" : "amuramoto",
        "applicationName" : "sandbox"
}

iOS

This example uses the iOS SDK.

SDK Method

(ApigeeClientResponse *)getEntities: (NSString *)endpoint query:(NSString *)query

Properties

Parameter Description
endpoint

The collection and entity identifier of the entity to be retrieved in the following format:

<collection>/<entity_UUID_or_name>
query

An optional query string. Requests for a specific entity should set the value to nil

Example Request/Response

Request:

-(NSString*)getEntity {

        //specify the entity collection and UUID or name to be retrieved        
        NSString *endpoint = @"items/b3aad0a4-f322-11e2-a9c1-999e12039f87";     
        
        NSString *query = nil;
        
        //we recommend you call ApigeeClient from your AppDelegate. 
        //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
        //create an instance of AppDelegate
        AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate];
        
        //call getEntities to initiate the API call
        ApigeeClientResponse *response = [appDelegate.dataClient getEntities:endpoint queryString:query];
        
        @try {
            //success
        }
        
        @catch (NSException * e) {
            //fail
        }

}                               
                                

Response:

{
        "action" : "get",
        "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://api.usergrid.com/amuramoto/sandbox/items",
        "entities" : [ {
                "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
                "type" : "item",
                "name" : "milk",
                "created" : 1378405020796,
                "modified" : 1378405020796,
                "metadata" : {
                          "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
                },
                "name" : "milk",
                "price" : "3.25"
        } ],
        "timestamp" : 1378405025763,
        "duration" : 31,
        "organization" : "amuramoto",
        "applicationName" : "sandbox"
}

Android

This example uses the Android SDK.

SDK Method

Asynchronous:

getEntitiesAsync(String type, String queryString, ApiResponseCallback callback)

Synchronous:

ApiResponse getEntities(String type, String queryString)

Properties

Parameter Description
type The entity type being retrieved
queryString

A query string that specifies the property of the entity to be retrieved in the following format:

<property>=<value>

To retrieve a specific entity, use the unique entity uuid or name property.

callback Callback function (Asynchronous calls only)

Example Request/Response

Request:

//Create client entity
String ORGNAME = "your-org";
String APPNAME = "your-app";        
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME);
ApigeeDataClient dataClient = apigeeClient.getDataClient();

String type = "item"; //entity type to be retrieved
String query = "uuid = b3aad0a4-f322-11e2-a9c1-999e12039f87;
    
//call getEntitiesAsync to initiate the asynchronous API call    
dataClient.getEntitiesAsync(type, query, new ApiResponseCallback() {    

//If getEntitiesAsync fails, catch the error
@Override
public void onException(Exception e) { 
        // Error
}

//If getEntitiesAsync is successful, handle the response object
@Override
public void onResponse(ApiResponse response) {
    try { 
        if (response != null) {
            // Success
        }
    } catch (Exception e) { //The API request returned an error
                // Fail
    }
}
});     
                                

Response:

{
"action":"post",
"application":"f34f4222-a166-11e2-a7f7-02e81adcf3d0",
"entities":[{
        "Client":{
                "accessToken":null,
                "apiUrl":"http://<baas_host_name>",
                "applicationId":"your-app",
                "clientId":null,
                "clientSecret":null,
                "currentOrganization":null,
                "loggedInUser":null,
                "organizationId":"your-org"
        },
        "type":"item",
        "uuid":"fd29157a-e980-11e2-afcc-652a12f1ce72",
        "created":1373475098695,
        "modified":1373475098695,
        "metadata":{
                "path":"/items/fd29157a-e980-11e2-afcc-652a12f1ce72"
        }
}],

"params":{},
"path":"/items",
"rawResponse":"{
        "action" : "get",
        "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://<baas_host_name>/your-org/your-app/items",
        "entities" : [ {
                "uuid" : "fd29157a-e980-11e2-afcc-652a12f1ce72",
                "type" : "item",
                "created" : 1373475098695,
                "modified" : 1373475098695,
                "metadata" : {
                        "path" : "/items/fd29157a-e980-11e2-afcc-652a12f1ce72"
                }
        } ],
        "timestamp" : 1373475098689,
        "duration" : 24,
        "organization" : "your-org",
        "applicationName" : "your-app"
}",
"uri":"http://<baas_host_name>/your-org/your-app/items",
"timestamp":1373475098689,
"entityCount":1,
"firstEntity":{
        "Client":{
                "accessToken":null,
                "apiUrl":"http://<baas_host_name>",
                "applicationId":"your-app",
                "clientId":null,
                "clientSecret":null,
                "currentOrganization":null,
                "loggedInUser":null,
                "organizationId":"your-org"
        },
        "type":"item",
        "uuid":"fd29157a-e980-11e2-afcc-652a12f1ce72",
        "created":1373475098695,
        "modified":1373475098695,
        "metadata":{
                "path":"/items/fd29157a-e980-11e2-afcc-652a12f1ce72"
        }
},
"lastEntity":{
        "Client":{
                "accessToken":null,
                "apiUrl":"http://<baas_host_name>",
                "applicationId":"your-app",
                "clientId":null,
                "clientSecret":null,
                "currentOrganization":null,
                "loggedInUser":null,
                "organizationId":"your-org"
        },
        "type":"item",
        "uuid":"fd29157a-e980-11e2-afcc-652a12f1ce72",
        "created":1373475098695,
        "modified":1373475098695,
        "metadata":{
                "path":"/items/fd29157a-e980-11e2-afcc-652a12f1ce72"
        }
},
"organization":"your-org",
"duration":24,
"applicationName":"your-app"
}       
                                

JavaScript (HTML5)

This example uses the JavaScript (HTML5) SDK.

SDK Method

getEntity(properties, callback)

Parameters

getEntity():

Parameter Description
properties

Object that contains the following properties of the entity to be retrieved:

  • type: the entity type to be retrieved
  • uuid: the uuid of the entity to be retrieved

You only need to specify name or uuid, not both.

callback Callback function

Example Request/Response

Request:

var properties = { 
        'type':'item',
        'uuid':'cac49d3a-4ca3-11e3-883a-4f96c6bf5114'
}; 
        
client.getEntity(properties, function (error, result) { 
        if (error) { 
          //error 
        } else { 
          //success 
        } 
});
                                

Response:

Usergrid.Entity {_client: Apigee.Client, _data: Object, serialize: function, get: function, set: function…}
        _client: Apigee.Client
                URI: "https://<baas_host_name>"
                _callTimeout: 30000
                _callTimeoutCallback: null
                _end: 1378413997721
                _start: 1378413997493
                appName: "your-app"
                buildCurl: false
                logging: true
                logoutCallback: null
                orgName: "your-org"
                __proto__: Object
        _data: Object
                created: 1378405020796
                metadata: Object
                modified: 1378405020796
                name: "milk"
                price: "3.25"
                type: "item"
                uuid: "5bb76bca-1657-11e3-903f-9ff6c621a7a4"
                __proto__: Object
        __proto__: Object                               
                                

Ruby

This example uses the RubyGem.

SDK Method

application[<entity_type>][<entity_uuid|entity_name>].entity

Parameters

Parameter Description
entity_type The entity type to be retrieved
entity_uuid|entity_name The name or UUID of the entity to be retrieved

Example Request/Response

Request:

#Create a client object
usergrid_api = 'https://<baas_host_name>'
organization = 'your-org'
application = 'your-app'

client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
# Retrieve the entity by referencing the [type] and [uuid or name]
# and save the response
response = client['items']['milk'].entity

rescue
#fail
end                             
                                

Response:

{
        "action" : "get",
        "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://api.usergrid.com/amuramoto/sandbox/items",
        "entities" : [ {
                "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
                "type" : "item",
                "name" : "milk",
                "created" : 1378405020796,
                "modified" : 1378405020796,
                "metadata" : {
                          "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
                },
                "name" : "milk",
                "price" : "3.25"
        } ],
        "timestamp" : 1378405025763,
        "duration" : 31,
        "organization" : "amuramoto",
        "applicationName" : "sandbox"
}

Node.js

This example uses the Node.js module.

SDK Method

getEntity(properties, callback)

Parameters

Object that contains the following properties of the entity to be retrieved:

  • type: the entity type to be retrieved
  • uuid: the uuid of the entity to be retrieved

You only need to specify name or uuid, not both.

Parameter Description
callback Callback function

Example Request/Response

Request:

var properties = { 
        method:'GET', 
        type:'items',
        uuid:'da4a50dc-38dc-11e2-b2e4-02e81adcf3d0' 
}; 

client.getEntity(properties, function (error, result) { 
        if (error) { 
          //error 
        } else { 
          //success 
        } 
});
                                

Response:

{ _client: 
   { URI: 'https://<baas_host_name>',
     orgName: 'your-org',
     appName: 'your-app',
     authType: 'NONE',
     clientId: undefined,
     clientSecret: undefined,
     token: null,
     buildCurl: false,
     logging: true,
     _callTimeout: 30000,
     _callTimeoutCallback: null,
     logoutCallback: null,
     _start: 1378423148601,
     _end: 1378423149028 },
  _data: 
   { method: 'GET',
     type: 'item',
     name: 'milk',
     uuid: '5bb76bca-1657-11e3-903f-9ff6c621a7a4',
     created: 1378405020796,
     modified: 1378405020796,
     metadata: { path: '/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4' },
     price: '3.25' } }