Creating Custom Data Entities

This article describes how to create custom data entities and entity properties. Entity types correspond to the name of collection to which they are posted. For example, if you create a new custom "dog" entity, a "dogs" collection will be created if one did not already exist. If a "dogs" collection already exists, the new "dog" entity will be saved in it. All user-defined properties are indexed, and strings that contain multiple words are keyword-indexed.

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.

Creating a custom entity

When a new entity is created, API Services will automatically create a corresponding collection if one does not already exist. The collection will automatically be named with the plural form of the entity type. For example, creating a custom entity of type 'item' will automatically create a collection named 'items' in which all future 'item' entities will be saved.

cURL

Request Syntax

curl -X POST https://<baas_host_name>/<org>/<app>/<entity_type> -d '{<property>, <property>, ...}'

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
entity_type Entity type to create. API Services will create a corresponding collection if one does not already exist. To add an entity to an existing collections, use the pluralized collection name for entity_type.
property Comma-separated list of entity properties, formatted as key-value pairs: <property>:<value> (for a full list of default properties, see Default Data Entity Types)

Example Request/Response

Request:

curl -X POST "https://<baas_host_name>/your-org/your-app/item" -d '{"name":"milk", "price":"3.25"}'

Response:

        { 
            "action" : "post", 
            "application" : "4a1edb70-d7a8-11e2-9ce3-f315e5aa568a", 
            "params" : { }, 
            "path" : "/items", "uri" : "http://api.usergrid.com/my-org/my-app/items", 
            "entities" : [ { 
                "uuid" : "83e9b7ea-e8f5-11e2-84df-e94123890c7a", 
                "type" : "item", 
                "name" : "milk", 
                "created" : 1373415195230, 
                "modified" : 1373415195230, 
                "metadata" : { 

                    "path" : "/items/83e9b7ea-e8f5-11e2-84df-e94123890c7a" 
                }, 
                "name" : "milk", 
                "price" : "3.25"
            } ], 
            "timestamp" : 1373415195225, 
            "duration" : 635, 
            "organization" : "my-org", 
            "applicationName" : "my-app" 
        }

iOS

This example uses the iOS SDK.

SDK Method

(ApigeeClientResponse *)createEntity:(NSDictionary *)newEntity

Parameters

Parameter Description
newEntity NSDictionary object that contains the entity properties

Example Request/Response

Request:

-(NSString*)newEntity {
        
        //create an entity object       
        NSMutableDictionary *entity = [[NSMutableDictionary alloc] init ];
        
        //Set entity properties
        [entity setObject:@"item" forKey:@"type"]; //Required. New entity type to create
        [entity setObject:@"milk" forKey:@"name"];
        [entity setObject:@"3.25" forKey:@"price"];
        
        //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 createEntity to initiate the API call
        ApigeeClientResponse *response = [appDelegate.dataClient createEntity:entity];
        
        @try {      
            //success       
        }
        @catch (NSException * e) {
            //fail
        }
    
}
                                

Response:

        { 
            "action" : "post", 
            "application" : "4a1edb70-d7a8-11e2-9ce3-f315e5aa568a", 
            "params" : { }, 
            "path" : "/items", "uri" : "http://api.usergrid.com/my-org/my-app/items", 
            "entities" : [ { 
                "uuid" : "83e9b7ea-e8f5-11e2-84df-e94123890c7a", 
                "type" : "item", 
                "name" : "milk", 
                "created" : 1373415195230, 
                "modified" : 1373415195230, 
                "metadata" : { 

                    "path" : "/items/83e9b7ea-e8f5-11e2-84df-e94123890c7a" 
                }, 
                "name" : "milk", 
                "price" : "3.25"
            } ], 
            "timestamp" : 1373415195225, 
            "duration" : 635, 
            "organization" : "my-org", 
            "applicationName" : "my-app" 
        }

Android

This example uses the Android SDK.

SDK Method

Asynchronous:

createEntityAsync(Map<String, Object> properties, ApiResponseCallback callback)

Synchronous:

ApiResponse createEntity(Map<String, Object> properties)

Parameters

Parameter Description
properties Map object that contains the entity properties. The 'type' property is required.
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,this.getBaseContext());
        ApigeeDataClient client = apigeeClient.getDataClient();

//Create properties object
Map<String, Object> properties = new HashMap<String, Object>();
properties.put("type", "item");
properties.put("name", "milk");
properties.put("price", "3.25");

//call createEntityAsync to initiate the asynchronous API call
apigeeClient.createEntityAsync(properties, new ApiResponseCallback() {
        
        //If createEntityAsync fails, catch the error
        @Override
        public void onException(Exception e) { 
                // Error
        }
        
        //If createEntityAsync 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" : "post",
                "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

createEntity(properties, callback)

Parameters

Parameter Description
properties

Object that contains the entity properties. The type property is required.

Optionally, you can set getOnExist:true, which returns an existing entity from the API if you try to create a new entity with the same name property as an entity that already exists.

callback Callback function

Example Request/Response

Request:

                        
//Create your client object
var client = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app'
});


//Set the properties of the entity
var options = {
        type:'item', //required
        name:'milk',
        price:'3.25'
};

//Create the entity and process the results
client.createEntity(options, function (error, result) {
        if (error) {
            //error
        } else {
            //success          
        }
});     
                                 

Response:

"_client": //Information on the client object used to initiate the call
        "URI":"https://<baas_host_name>",
        "orgName":"your-org",
        "appName":"your-app",
        "buildCurl":false,
        "logging":false,
        "_callTimeout":30000,
        "_callTimeoutCallback":null,
        "logoutCallback":null,
        "_start":1373482218757,
        "_end":1373482219070,
"_data": //Information on the successfully created entity
        "type":"item",
        "name":"milk",
        "price":"3.25",
        "uuid":"9124211a-e991-11e2-ba6c-e55e3ffa12ef",
        "created":1373482218913,
        "modified":1373482218913,
        "metadata":
                "path":"/items/9124211a-e991-11e2-ba6c-e55e3ffa12ef"                                    
                                

Ruby

This example uses the RubyGem.

SDK Method

create_entity(type, properties)

Parameters

Parameter Description
type Custom entity type to create
properties Object that contains the entity properties

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
        # Call create_entity to initiate the API call
        # and save the response
        response = client.create_entity 'item', {'name' => 'milk', 'price' => '3.25'}
        new_item=response.entity
rescue
        #fail
end
                                

Response:

        { 
            "action" : "post", 
            "application" : "4a1edb70-d7a8-11e2-9ce3-f315e5aa568a", 
            "params" : { }, 
            "path" : "/items", "uri" : "http://api.usergrid.com/my-org/my-app/items", 
            "entities" : [ { 
                "uuid" : "83e9b7ea-e8f5-11e2-84df-e94123890c7a", 
                "type" : "item", 
                "name" : "milk", 
                "created" : 1373415195230, 
                "modified" : 1373415195230, 
                "metadata" : { 

                    "path" : "/items/83e9b7ea-e8f5-11e2-84df-e94123890c7a" 
                }, 
                "name" : "milk", 
                "price" : "3.25"
            } ], 
            "timestamp" : 1373415195225, 
            "duration" : 635, 
            "organization" : "my-org", 
            "applicationName" : "my-app" 
        }

Node.js

The example assumes use of the Node.js module.

SDK Method

createEntity(properties, callback)

Parameters

Parameter Description
properties Object that contains the entity properties. The 'type' property is required.
callback Callback function

Example Request/Response

Request:

//Create a client object
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app'
});

//Set the properties for your entity
var properties = {
        type:"item", //Requried. Type of entity to create.
        name:"milk",
        price:"3.25"
};

//Call createEntity to initiate the API call
dataClient.createEntity(properties, function(error, result){
        if(error) {
                //error
        } else {
                //success
        }
});
                                

Response:

{ 
        type: 'item',
        name: 'milk',
        price: '3.25',
        uuid: '126e29aa-eb40-11e2-85a8-355b0e586a1a',
        created: 1373667119418,
        modified: 1373667119418,
        metadata: { path: '/items/126e29aa-eb40-11e2-85a8-355b0e586a1a' } 
}                       
                                

Creating multiple custom entities

cURL

Request Syntax

curl -X POST https://<baas_host_name>/<org>/<app>/<entity_type>/ -d '[{<entity>}, {<entity>}, ...]'

Parameters

Parameter Description
org Organization UUID or name
app Application UUID or name
entity_type Custom entity type to create. API Services will create a corresponding collection if one does not already exist. To add an entity to an existing collections, use the collection name or colleciton UUID in place of the entity type.
entity Comma-separated list of entity objects to create. Each object should be formatted as a comma-separated list of entity properties, formatted as key-value pairs in the format <property>:<value>

Example Request/Response

Request:

curl -X POST "https://<baas_host_name>/your-org/your-app/item" -d '[{"name":"milk", "price":"3.25"}, {"name":"bread", "price":"2.50"}]'

Response:

{
        "action" : "post",
        "application" : "f34f4222-a166-11e2-a7f7-02e9sjwsf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://api.usergrid.com/your-org/your-app/items",
        "entities" : [ {
                "uuid" : "f3a8061a-ef0b-11e2-9e92-5f4a65c16193",
                "type" : "item",
                "name" : "milk",
                "price" : "3.25",
                "created" : 1374084538609,
                "modified" : 1374084538609,
                "metadata" : {
                        "path" : "/multis/f3a8061a-ef0b-11e2-9e92-5f4a65c16193"
                },
                "name" : "milk"
        }, {
                "uuid" : "f3be262a-ef0b-11e2-a51b-6715d5ef47a6",
                "type" : "item",
                "name" : "bread",
                "price" : "2.50",
                "created" : 1374084538754,
                "modified" : 1374084538754,
                "metadata" : {
                        "path" : "/items/f3be262a-ef0b-11e2-a51b-6715d5ef47a6"
                },
                "name" : "bread"
        } ],
        "timestamp" : 1374084538584,
        "duration" : 388,
        "organization" : "your-org",
        "applicationName" : "your-app"
}

iOS

This example uses the iOS SDK.

SDK Method

The iOS SDK does not have a dedicated method for creating multiple entities. Instead, you can use the generic apiRequest method to form the API request manually.

(ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)http_method data:(NSString *)properties

Parameters

Parameter Description
url

Fully-formed request URL in the format:

https://<baas_host_name>/<your-org>/<your-app>/<collection>
http_method HTTP Method – in this case POST
properties A JSON array, containing a JSON object of entity properties for each entity to be created. The 'type' property is required for each entity.

Example Request/Response

Request:

                        
-(NSString*)newMultipleEntities {

    //apiRequest requires us to form the full API request, including base URL, org name, and app name.
        //Note that we specify the target collection in the URL string
    NSString * url = @"https://<baas_host_name>/your-org/your-app/items";
    NSString * http_method = @"POST";
    NSString * properties = @"[{\"name\":\"milk\",\"price\":\"3.25\"},{\"name\":\"bread\",\"price\":\"2.50\"}]"; //We escape the double quotes in the request body
    
        //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 createEntity to initiate the API call
        ApigeeClientResponse *response = [appDelegate.dataClient apiRequest:url operation:http_method data:properties];

    @try {
        
       //success
        
    }
    @catch (NSException * e) {
        //fail
    }
    
}
                                

Response:

{
        "action" : "post",
        "application" : "f34f4222-a166-11e2-a7f7-02e9sjwsf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://api.usergrid.com/your-org/your-app/items",
        "entities" : [ {
                "uuid" : "f3a8061a-ef0b-11e2-9e92-5f4a65c16193",
                "type" : "item",
                "name" : "milk",
                "price" : "3.25",
                "created" : 1374084538609,
                "modified" : 1374084538609,
                "metadata" : {
                        "path" : "/multis/f3a8061a-ef0b-11e2-9e92-5f4a65c16193"
                },
                "name" : "milk"
        }, {
                "uuid" : "f3be262a-ef0b-11e2-a51b-6715d5ef47a6",
                "type" : "item",
                "name" : "bread",
                "price" : "2.50",
                "created" : 1374084538754,
                "modified" : 1374084538754,
                "metadata" : {
                        "path" : "/items/f3be262a-ef0b-11e2-a51b-6715d5ef47a6"
                },
                "name" : "bread"
        } ],
        "timestamp" : 1374084538584,
        "duration" : 388,
        "organization" : "your-org",
        "applicationName" : "your-app"
}

Android

Currently, creating multiple entities is not supported by the Android SDK.

JavaScript (HTML5)

This example uses the JavaScript (HTML5) SDK.

SDK Method

request(options, callback)

Parameters

Parameter Description
options Object that contains the following properties:
  • endpoint: the collection to add the entities to
  • method: the HTTP method for the request - in this case POST
  • body: the body of the request – in this case, a JSON-array containing an object with properties for each entity to be created.
callback Callback function

Example Request/Response

Request:

//Create a client object with your organization name and application name.
var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app'
});

//Set the request options: http method, endpoint, body
var options = {
        method:'POST',
        endpoint:'items', //The collection name
        body:[{"name":"milk", "price":"3.25"},{"name": "bread", "price":"3.25"}] //note the multiple JSON objects
};

//Call request() to initiate the API call and process the results
client.request(options, function (error, result) {
    if (error) {
        //error
    } else {
        //success        
    }
});
                                

Response:

Object {action: "post", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://<baas_host_name>/your-org/your-app/items"…}
        action: "post"
        application: "f34f4222-a166-11e2-a7f7-02e8js76g3d0" //your application uuid
        applicationName: "your-app"
        duration: 315
        entities: Array[2] //array of entities successfully created
                0: Object //entity 1
                        created: 1374099532148
                        metadata: Object
                        modified: 1374099532148
                        name: "milk"
                        price: "3.25"
                        type: "item"
                        uuid: "dc80834a-ef2e-11e2-8a77-cf8d4c2dbd49"
                        __proto__: Object
                1: Object //entity 2
                        created: 1374099532344
                        metadata: Object
                        modified: 1374099532344
                        name: "bread"
                        price: "3.25"
                        type: "item"
                        uuid: "dc9e6b8a-ef2e-11e2-8e8b-e39a2d988c4f"
        length: 2
        organization: "your-org"
        params: Object
        __proto__: Object
                path: "/items"
                timestamp: 1374099532139
                uri: "http://<baas_host_name>/your-org/your-app/items"                            
                                

Ruby

This example uses the RubyGem.

SDK Method

create_entity(type, properties)

Properties

Parameter Description
type Custom entity type to create
properties Object that contains the entity properties

Example Request/Response

#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
        # Call create_entity to initiate the API call - note the multiple JSON objects
        # and save the response
        response = client.create_entity 'multi', [{'name'=> 'milk', 'price' => '3.25'},{'name'=> 'bread', 'price' => '2.50'}]
        new_items=response.entity
rescue
        #fail
end                     
                                

Response:

{
        "action" : "post",
        "application" : "f34f4222-a166-11e2-a7f7-02e9sjwsf3d0",
        "params" : { },
        "path" : "/items",
        "uri" : "http://api.usergrid.com/your-org/your-app/items",
        "entities" : [ {
                "uuid" : "f3a8061a-ef0b-11e2-9e92-5f4a65c16193",
                "type" : "item",
                "name" : "milk",
                "price" : "3.25",
                "created" : 1374084538609,
                "modified" : 1374084538609,
                "metadata" : {
                        "path" : "/multis/f3a8061a-ef0b-11e2-9e92-5f4a65c16193"
                },
                "name" : "milk"
        }, {
                "uuid" : "f3be262a-ef0b-11e2-a51b-6715d5ef47a6",
                "type" : "item",
                "name" : "bread",
                "price" : "2.50",
                "created" : 1374084538754,
                "modified" : 1374084538754,
                "metadata" : {
                        "path" : "/items/f3be262a-ef0b-11e2-a51b-6715d5ef47a6"
                },
                "name" : "bread"
        } ],
        "timestamp" : 1374084538584,
        "duration" : 388,
        "organization" : "your-org",
        "applicationName" : "your-app"
}

Node.js

The example uses the Node.js module.

SDK Method

request(options, callback)

Parameters

Parameter Description
options Object that contains the following properties:
  • endpoint: the collection to add the entities to
  • method: the HTTP method for the request – in this case POST
  • body: the body of the request. In this case, a JSON-formatted set of objects containing entity properties.
callback Callback function

Example Request/Response

Request:

//Create a client object
var dataClient = new Usergrid.client({
        orgName:'your-org',
        appName:'your-app'
});                     
                        
//Set the request options: http method, endpoint, body
var options = {
method:'POST',
endpoint:'items', //The collection name
body:[{"name":"milk", "price":"3.25"},{"name": "bread", "price":"3.25"}] //note the multiple JSON objects
};

//Call request() to initiate the API call and process the results
dataClient.request(options, function (error, result) {
    if (error) {
        //error
    } else {
        //success — result will contain raw results from API call        
    }
});

                        

Response:

{
        "action": "post",
        "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e221",
        "params":       {},
        "path": "/items",
        "uri": "https://<baas_host_name>/22000a1c4e22-7fsii8t1-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/cats",
        "entities":     [
                {
                        "uuid": "187d31d9-0742-11e2-a7b5-12313d21509c",
                        "type": "item",
                        "name": "milk",
                        "price" : "3.25"
                        "created": 1348599123463,
                        "modified": 1348599123463,
                        "metadata":     {
                                "path": "/items/187d31d9-0742-11e2-a7b5-12313d21509c"
                                }
                },
                {
                        "uuid": "188f815b-0742-11e2-a7b5-12313d21509c",
                        "type": "items",
                        "name": "bread",
                        "price" : "2.50"
                        "created": 1348599123583,
                        "modified": 1348599123583,
                        "metadata":     {
                                                        "path": "/cats/187d31d9-0742-11e2-a7b5-12313d21509c"
                        }
                }
        ],
        "timestamp":    1348599123461,
        "duration": 415,
        "organization": "your-org",
        "applicationName": "your-app"
}
                        

Send feedback about...

Apigee Docs