General-purpose endpoints

See all application entities

This document describes App services endpoints for managing entities other than users, groups, and roles.

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 new entity or collection

Use the POST method to post an entity to the specified collection.

Collections do not need to be defined before being used; simply posting an entity to a collection creates the collection if it does not already exist.

Request URI

POST /{org_id}/{app_id}/{collection}{request body}

Parameters

Parameter Description
arg uuid|string org_id Organization UUID or organization name
arg uuid|string app_id Application UUID or application name
arg string collection Collection name
request body

Either a single property or set of entity properties:

{ "foo" : "bar", "a" : { "b" : 1, "c" : 2 } }

or an array to create multiple entities in the same collection:

[ { "foo" : "bar" }, { "foo" : "baz"} ]

Example - Request: Create an entity

cURL

curl -X POST "https://api.usergrid.com/my-org/my-app/cats" -d '{"name":"nico"}'

JavaScript (HTML5)

The example assumes use of the JavaScript (HTML5) SDK.

var options = {
    method:'POST',
    endpoint:'cats',
    body: {name:'nico'}
};
client.createEntity(options, function (err, cat) {
    if (err) {
        //error
    } else {
        //success          
    }
});

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_cat name: 'nico'
mynewcat = result.entity

Node.js

The example assumes use of the Node.js module.

var options = {
    method:'POST',
    endpoint:'cats',
    body: {name:'nico'}
};
client.createEntity(options, function (err, cat) {
    if (err) {
        //error
    } else {
        //success          
    }
});

Example - Response

{
"action": "post",
"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
"params": {},
"path": "/cats",
"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/cats",
"entities": [
       {
        "uuid": "1a7c2177-67cb-11e1-8223-12313d14bde7",
        "type": "cat",
        "name": "nico",
        "created": 1331065781819,
        "modified": 1331065781819,
        "metadata": {
          "path": "/cats/1a7c2177-67cb-11e1-8223-12313d14bde7"
        },
      }
],
"timestamp": 1331065781798,
"duration": 74,
"organization": "my-org",
"applicationName": "my-app"
}

Example - Request: Create multiple entities

cURL

curl -X POST "https://api.usergrid.com/my-org/my-app/cats" -d '[ {"name":"mopsy"},{"name": "topsy"}]

JavaScript (HTML5)

The example assumes use of the JavaScript (HTML5) SDK.

Note
var options = {
    method:'POST',
    endpoint:'cats',
    body:[{"name":"mopsy"},{"name": "topsy"}]
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success — data will contain raw results from API call        
    }
});

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result=app.create_cats [{name: "mopsy"}, {name: "topsy"}]
cats = result.collection

Node.js

The example assumes use of the Node.js module.

Note
var options = {
    method:'POST',
    endpoint:'cats',
    body:[{"name":"mopsy"},{"name": "topsy"}]
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success — data will contain raw results from API call        
    }
});

Example - Response

{
 "action": "post",
 "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e221",
 "params":  {},
 "path": "/cats",
 "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/cats",
 "entities":  [
    {
     "uuid": "187d31d9-0742-11e2-a7b5-12313d21509c",
     "type": "cat",
     "name": "mopsy",
     "created": 1348599123463,
     "modified": 1348599123463,
     "metadata":  {
       "path": "/cats/187d31d9-0742-11e2-a7b5-12313d21509c"
     }
   },
    {
    "uuid": "188f815b-0742-11e2-a7b5-12313d21509c",
    "type": "cat",
    "name": "topsy",
    "created": 1348599123583,
    "modified": 1348599123583,
    "metadata":  {
        "path": "/cats/187d31d9-0742-11e2-a7b5-12313d21509c"
    }
   }
  ],
  "timestamp": 1348599123461,
  "duration": 415,
  "organization": "my-org",
  "applicationName": "my-app"

Entity contents are specified in JSON format. Any valid JSON object can be stored in an entity, regardless of the level of complexity, and can be more than just name/value pairs. For example, an entity can contain subentities.

Example - Request: Create an entity with subentities

cURL

curl -X POST "https://api.usergrid.com/my-org/my-app/cats" -d '{"name":"phantom","awardcodes":{"BIS":"Best in show","FRU":"First runner up", "SRU":"Second runner up"}}'

JavaScript (HTML5)

The example assumes use of the JavaScript (HTML5) SDK.

var options = {
        method:'POST',
        endpoint:'cats',
        body:{ 
          name:'phantom', 
          awardcodes:'{"BIS":"Best in show",FRU:"First runner up", SRU:"Second runner up"}' }
    };
client.createEntity(options, function (err, cat) {
    if (err) {
        //error
    } else {
        //success          
    }
});

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_cat name: 'phantom', awardcodes: { counters: {BIS: 'Best in show', FRU: 'First runner up', SRU: 'Second runner up'}}

Node.js

The example assumes use of the Node.js module.

var options = {
        method:'POST',
        endpoint:'cats',
        body:{ 
          name:'phantom', 
          awardcodes:'{"BIS":"Best in show",FRU:"First runner up", SRU:"Second runner up"}' }
    };
client.createEntity(options, function (err, cat) {
    if (err) {
        //error
    } else {
        //success          
    }
});

Example - Response

{
 "action": "post",
 "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
 "params":  {},
 "path": "/cats",
 "uri":      "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/cats",
 "entities":  [
    {
     "uuid": "b5c88a20-08ce-11e2-9d8d-12313d04be1e",
     "type": "cat",
     "name": "phantom",
     "created": 1331065781819,
     "modified": 13310657818194,
     "awardcodes":  {
       "BIS": "Best in show",
       "FRU": "First runner up",
       "SRU": "Second runner up"
     },
     "metadata":  {
       "path": "/cats/b5c88a20-08ce-11e2-9d8d-12313d04be1e"
     }
   }
 ],
 "timestamp": 1348769467049,
 "duration": 3508,
 "organization": "my-org",
 "applicationName": "my-app"

Entity types are defined by the type of collection to which they are posted. For example, posting to a collection named “cats” creates entities of type cat.

All user-defined properties are indexed. Entities are fully indexed, and strings that contain multiple words are keyword-indexed as well.

For all application-specific entities, you can provide a property called name that you can use to retrieve the entity rather than its UUID. The value for the name property must be unique. Some predefined entities (such as user) specify a different look-up property that can be used for identifying an entity. For example, user entities specify the username property rather than name. Refer to specific system-defined entity descriptions for details.

Getting an entity

Use the GET method to retrieve an entity given the specified UUID or entity lookup property.

For any application-specific entity type, if there is a name property specified for the entity, you can specify name instead of the UUID to retrieve the entity. For system-provided entities, there might be a different property than name defined for doing look-ups. For example, the user entity defines username as its look-up property. Refer to the entity descriptions to see if there is an alternate look-up property defined for a system-provided entity type.

Request URI

GET /{org_id}/{app_id}/{collection}/{uuid|name}

Parameters

Parameter Description
arg uuid|string org_id Organization UUID or organization name
arg uuid|string app_id Application UUID or application name
arg string collection Collection name
arg uuid|string uuid|name Entity UUID or name

When the entity is a user, use username instead of name to retrieve the entity.

Example - Request

cURL

curl -X GET "https://api.usergrid.com/my-org/my-app/things/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"

JavaScript (HTML5)

The example assumes use of the JavaScript (HTML5) SDK.

//If you already have your entity object, and just want to fetch the data for it from the database, you can just call fetch:

myEntity.fetch(function(err){
    if (err){
        //entity not refreshed from database
    } else {
        //entity has been refreshed from the database
    }
});
//You can also make a straight GET request: 

var options = { 
   method:'GET', 
   endpoint:'things/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0' 
}; 
client.request(options, function (err, data) { 
   if (err) { 
      //error 
   } else { 
      //success — data will contain raw results from API call 
   } 
});

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
thing = app['things/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0'].entity

Node.js

The example assumes use of the Node.js module.

//If you already have your entity object, and just want to fetch the data for it from the database, you can just call fetch:

myEntity.fetch(function(err){
    if (err){
        //entity not refreshed from database
    } else {
        //entity has been refreshed from the database
    }
});
//You can also make a straight GET request: 

var options = { 
   method:'GET', 
   endpoint:'things/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0b' 
}; 
client.request(options, function (err, data) { 
   if (err) { 
      //error 
   } else { 
      //success — data will contain raw results from API call 
   } 
});

Example - Response

{
    "action": "get",
    "application": "438a1ca1-cf9b-11e0-bcc1-12313f0204bb",
    "params": {}
    "path": "/things",
    "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/things",
    "entities": [
        {
            "uuid": "da4a50dc-38dc-11e2-b2e4-02e81adcf3d0",
            "type": "thing",
            "created": 1315357451966016,
            "modified": 1315357451966016,
            "metadata": {
                "path": "/things/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"
            }
        }
    ],
    "timestamp": 1315357451949,
    "duration": 52,
    "organization": "my-org",
    "applicationName": "my-app"
}

Example - Request: Get multiple entities

You can retrieve multiple entities by specifying their UUIDs in the resource path. You cannot specify entity names. Use a semicolon (not a slash) to separate the collection name from the UUIDs and a semicolon to separate each UUID.

cURL

curl -X GET "https://api.usergrid.com/my-org/my-app/cats;2d6de40f-072f-11e2-a7b5-12313d21509c;92643d37-666c-11e2-8b37-02e81ac5a17b"

JavaScript (HTML5)

The example assumes use of the JavaScript (HTML5) SDK.

var options = {
    method:'GET',
    endpoint:'cats;2d6de40f-072f-11e2-a7b5-12313d21509c;92643d37-666c-11e2-8b37-02e81ac5a17b'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
cats = app['cats;2d6de40f-072f-11e2-a7b5-12313d21509c;92643d37-666c-11e2-8b37-02e81ac5a17b'].entity

Node.js

The example assumes use of the Node.js module.

var options = {
    method:'GET',
    endpoint:'cats;2d6de40f-072f-11e2-a7b5-12313d21509c;92643d37-666c-11e2-8b37-02e81ac5a17b'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response: Get multiple entities

{
  "action" : "get",
  "application" : "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
  "params" : { },
  "path" : "/cats",
  "uri" : "http://api.usergrid.com/edort1/sandbox/cats",
  "entities" : [ {
    "uuid" : "92643d37-666c-11e2-8b37-02e81ac5a17b",
    "type" : "cat",
    "name" : "tabby",
    "created" : 1359062727308,
    "modified" : 1359062727308,
    "metadata" : {
      "path" : "/cats/92643d37-666c-11e2-8b37-02e81ac5a17b"
    },
    "name" : "tabby"
  }, {
    "uuid" : "2d6de40f-072f-11e2-a7b5-12313d21509c",
    "type" : "cat",
    "name" : "fluffy",
    "created" : 1348590998157,
    "modified" : 1350688632830,
    "awards" : [ {
      "event" : "Pacific Cat Fanciers",
      "designation" : "First Runner Up"
    }, {
      "event" : "Cat World",
      "designation" : "Blue Ribbon"
    } ],
    "metadata" : {
      "path" : "/cats/2d6de40f-072f-11e2-a7b5-12313d21509c"
    },
    "name" : "fluffy"
  } ],
  "timestamp" : 1360255095608,
  "duration" : 32,
  "organization" : "my-org",
  "applicationName" : "my-app"
}

Updating an entity

Use the PUT method to update an entity in a collection. New property values are stored in the entity.

Request URI

PUT /{org_id}/{app_id}/{collection}/{uuid|name}{request body}

Parameters

Parameter Description
arg uuid|string org_id Organization UUID or organization name
arg uuid|string app_id Application UUID or application name
arg string collection Collection name
arg uuid|string uuid|name Entity UUID or name
request body

Set of entity properties:

{"alpha":"bravo"}

Example - Request

cURL

curl -X PUT https://api.usergrid.com/my-org/my-app/things/4c469e8a-d8ed-11e0-bcc1-12313f0204bb" -d '{"alpha":"bravo"}'

JavaScript (HTML5)

The example assumes use of the JavaScript (HTML5) SDK.

//after  the entity is created, you can set single properties:
myEntity.set('data','Value');

//or set a full JSON object:
var data = {
   somedata:'one',
   someotherdata:'two'
}
//set is additive, so previously set properties are not overwritten
myEntity.set(data);

//finally, call save on the object to save it back to the database
myEntity.save(function(err){
   if (err){
      //error
   } else {
      //success
   }
});

//You can also simply make a straight PUT call to the database: 
var options = { 
   method:'PUT', 
   endpoint:'things/4c469e8a-d8ed-11e0-bcc1-12313f0204bb', 
   body:{ alpha:'bravo' } 
}; 
client.request(options, function (err, data) { 
   if (err) { 
      //error 
   } else { 
      //data will contain raw results from API call 
      //success 
   } 
});

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
thing = app['things/4c469e8a-d8ed-11e0-bcc1-12313f0204bb'].entity
thing.alpha = 'bravo'
thing.save

Node.js

The example assumes use of the Node.js module.

//after  the entity is created, you can set single properties:
myEntity.set('data','Value');

//or set a full JSON object:
var data = {
   somedata:'one',
   someotherdata:'two'
}
//set is additive, so previously set properties are not overwritten
myEntity.set(data);

//finally, call save on the object to save it back to the database
myEntity.save(function(err){
   if (err){
      //error
   } else {
      //success
   }
});

//You can also simply make a straight PUT call to the database: 
var options = { 
   method:'PUT', 
   endpoint:'things/4c469e8a-d8ed-11e0-bcc1-12313f0204bb', 
   body:{ alpha:'bravo' } 
}; 
client.request(options, function (err, data) { 
   if (err) { 
      //error 
   } else { 
      //data will contain raw results from API call 
      //success 
   } 
});