Was this Helpful?

This article describes how to create collections in Advanced API Services. All entities are automatically associated with a corresponding collection based on the type property of the entity. You may create empty collections if you wish, but creating an entity of a new type will automatically create a corresponding collection for you. For example, creating a new custom "item" entity, creates an "items" collection.

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 collection

The following examples show how to create an empty collection. Alternatively, you can create a collection simply by creating a new entity with a 'type' property that corresponds to the collection you wish to create. For more on creating entities, see Creating Custom Data Entities

The easiest way to create a new, empty collection is by using the Data Explorer tool in the Admin Portal by doing the following:

  1. Login to the Admin Portal.
  2. In the left menu, click Data Explorer.
  3. In the middle column, click the Add Collection button.
  4. In the form, enter the name for the collection you want to create. If the provided value is not a plural word, API Services will pluralize it.
  5. Click Create. The new collection will appear in the list.

Request Syntax

curl -X POST https://api.usergrid.com/<org>/<app>/<collection_name>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
collection_name

Name of the collection to create. If the provided value is not a plural word, API Services will pluralize it.

For example, providing 'item' will create a collection named 'items' but providing 'items' will not create 'itemses'.

Example Request/Response

Request:

curl -X POST "https://api.usergrid.com/your-org/your-app/item"

Response:

Was this Helpful?
{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ ],
  "timestamp" : 1378857079220,
  "duration" : 31,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

This example uses the iOS SDK.

SDK Method

(ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData

Parameters

Parameter Description
url A fully-formed url in the following format:
https://api.usergrid.com/<org>/<app>/<collection>
op The HTTP method - in this case, 'POST'
opData No data is being sent, so the value is nil

Example Request/Response

Request:

-(NSString*)createCollection {

NSString *url = @"https://api.usergrid.com/your-org/your-app/items";
NSString *op = @"POST";
NSString *opData = 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 createEntity to initiate the API call
	ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData];

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

}
				

Response:

Was this Helpful?
{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ ],
  "timestamp" : 1378857079220,
  "duration" : 31,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

Currently, creating an empty collection is not supported by the SDK for Android; however you can create a collection by creating an entity with a 'type' property that corresponds to the collection you wish to create. For more information, see Creating Custom Data Entities.

This example uses the JavaScript (HTML5) SDK.

SDK Method

request(options, callback)

Parameters

Parameter Description
options

A JSON-formatted object containing the following properties:

  • endpoint: the name of the collection to be created
  • method: the HTTP method for the request, in this case POST
callback Callback function to handle the API response

Example Request/Response

Request:

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

//options for the request
var options = {
endpoint:"items",
method:"POST"
}

dataClient.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://api.usergrid.com/your-org/your-app/items"…}
action: "post"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 29
entities: Array[0]
organization: "your-org"
params: Object
path: "/items"
timestamp: 1378872945962
uri: "http://api.usergrid.com/your-org/your-app/items"
__proto__: Object				
				

This example uses the RubyGem.

SDK Method

create_entity(type, properties)

Parameters

Parameter Description
type Custom entity type that will correspond to the collection
properties Object that contains the entity properties – in this case 'nil'

Example Request/Response

Request:

#Create a client object
usergrid_api = 'https://api.usergrid.com'
organization = 'your-org'
application = 'your-app'

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

begin
	# Call create_entity to initiate the API call
	# By specifying 'nil' for the request body, we get an empty collection
	client.create_entity('item', nil)
rescue
	#fail
end
				

Response:

Was this Helpful?
{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ ],
  "timestamp" : 1378857079220,
  "duration" : 31,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

This example uses the Node.js module.

SDK Method

entity.request(options,callback)

Parameters

Parameter Description
options

A JSON-formatted object containing the following properties:

  • endpoint: the name of the collection to be created
  • method: the HTTP method for the request, in this case POST
callback Callback function to handle the API response

Example Request/Response

Request:

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

//options for the request
var options = {
endpoint:"items",
method:"POST"
}

dataClient.request(options,function (error, result) {

	if (error) { 
	    // Error
	} else { 
		// Success
	}

});    	
				

Response:

{ action: 'post',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: {},
  path: '/items',
  uri: 'http://api.usergrid.com/your-org/your-app/items',
  entities: [],
  timestamp: 1378873689426,
  duration: 29,
  organization: 'your-org',
  applicationName: 'your-app' }
				

 

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?)