Entities¶

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.

The methods cited in this article should be used to create custom data entities. If you are using one of the Usergrid SDKs, use one of the entity type-specific SDK methods to create default data entities.

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, Usergrid 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.

Request Syntax¶

curl -X POST https://api.usergrid.com/<org>/<app>/<entity_type> -d 'json_object'

Parameters

Parameter	Description
org	Organization UUID or organization name
app	Application UUID or application name
entity_type	Entity type to create.
json_object	JSON representation of entity properties

(For a full list of default properties, see Default Data Entity Types)

Usergrid 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.

Example Request/Response¶

Request:

curl -X POST "https://api.usergrid.com/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"
}

Creating multiple custom entities¶

Request Syntax¶

curl -X POST https://api.usergrid.com/<org>/<app>/<entity_type>/ -d 'json_array'

Parameters

Parameter	Description
org	Organization UUID or name
app	Application UUID or name
entity_type	Custom entity type to create.
json_array	JSON array of entities to be created.

Usergrid will create a corresponding collection if one does not already exist. To add an entity to an existing collections, use the collection name or collection UUID in place of the entity type.

Example Request/Response¶

Request:

curl -X POST "https://api.usergrid.com/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"
}

Creating an entity with sub-properties¶

Any valid JSON object can be stored in an entity, regardless of the level of complexity, including sub-properties. For example, suppose you have an ‘items’ collection that contains an entity named ‘milk’. You might store the different varieties of milk as sub-properties of a ‘varieties’ property:

{
    "type" : "item"
    "name" : "milk"
    "varieties" : [ {
        "name" : "1%",
        "price" : "3.25",
        "sku" : "0393847575533445"
    }, {
        "name" : "whole",
        "price" : "3.85",
        "sku" : "0393394956788445"
    }, {
        "name" : "skim",
        "price" : "4.00",
        "sku" : "0390299933488445"
    } ]
}

Updating sub-properties¶

An array of sub-properties is treated as a single object. This means that sub-properties cannot be updated atomically. All sub-properties of a given property must be updated as a set. For more on updating an existing sub-property, see Updating Data Entities.

Example Request/Response

Request:
//Note the use of square brackets for specifying multiple nested objects
curl -X POST "https://api.usergrid.com/your-org/your-app/items" -d '{"varieties":[{"name":"1%","price" : "3.25", "sku" : "0393847575533445"},{"name" : "whole", "price" : "3.85", "sku" : "0393394956788445"}, {"name" : "skim", "price" : "4.00", "sku" : "0390299933488445"}]}'
Response:
{
    "action" : "post",
    "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
    "params" : { },
    "path" : "/items",
    "uri" : "http://api.usergrid.com/your-org/your-app/items",
    "entities" : [ {
        "uuid" : "0d7cf92a-effb-11e2-917d-c5e707256e71",
        "type" : "item",
        "name" : "milk",
        "created" : 1374187231666,
        "modified" : 1374187231666,
        "metadata" : {
            "path" : "/items/0d7cf92a-effb-11e2-917d-c5e707256e71"
        },
        "name" : "milk",
        "varieties" : [ {
            "name" : "1%",
            "price" : "3.25",
            "SKU" : "0393847575533445"
        }, {
            "name" : "whole",
            "price" : "3.85",
            "SKU" : "0393394956788445"
        }, {
            "name" : "skim",
            "price" : "4.00",
            "SKU" : "0390299933488445"
        } ]
    } ],
    "timestamp" : 1374187450826,
    "duration" : 50,
    "organization" : "your-org",
    "applicationName" : "your-app"
}

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.

With the exception of the user entity, all data entities can be retrieved by using their UUID or a ‘name’ property. The user entity can be retrieved by UUID or the ‘username’ property. The value for the ‘name’ or ‘username’ property must be unique.

Retrieving an entity¶

Request Syntax¶

curl -X GET https://api.usergrid.com/<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://api.usergrid.com/your-org/your-app/items/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"

Retrieve by ‘name’ property:

curl -X GET "https://api.usergrid.com/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"
}

Retrieving multiple entities¶

This example describes how to retrieve multiple entities by UUID. You can also retrieve a set of entities by using a query string. For more information on querying your data, see Querying your data.

Request Syntax¶

curl -X GET https://api.usergrid.com/<org_id>/<app_id>/<collection>?ql= uuid = <entity_uuid> OR uuid = <entity_uuid>; ...

Parameters

Parameter	Description
org_id	Organization UUID or organization name
app_id	Application UUID or application name
collection	Collection UUID or collection name
query	A url-encoded query string of entity properties to be matched.

The query must be in Usergrid Query Language, for example:

?ql=uuid="<entity_uuid>"" OR name="<entity_name>" OR...

You may also specify the following for certain entity types:

User entities: username =

All other entities except groups: name =

Example Request/Response¶

Request:

//note the url-encoded query string
curl -X GET "https://api.usergrid.com/your-org/your-app/items?ql=name%3D'milk'%20OR%20UUID%3D1a9356ba-1682-11e3-a72a-81581bbaf055&limit="

Note: The query parameter of the request must be url encoded for curl requests

Response:

{
      "action" : "get",
      "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
      "params" : {
            "ql" : [ "name='milk' OR UUID=1a9356ba-1682-11e3-a72a-81581bbaf055" ]
      },
      "path" : "/items",
      "uri" : "http://api.usergrid.com/your-org/your-app/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"
      }, {
        "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055",
        "type" : "item",
        "name" : "bread",
        "created" : 1378423379867,
        "modified" : 1378423379867,
        "metadata" : {
              "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055"
        },
            "name" : "bread",
            "price" : "2.50"
      } ],
      "timestamp" : 1378423793729,
      "duration" : 63,
      "organization" : "your-org",
      "applicationName" : "your-app",
      "count" : 2
}

Updating Data Entities¶

This article describes how to update entities in 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.

Updating an entity¶

One or more properties can be updated with a single PUT request. For information on updating sub-properties, see Updating sub-properties below.

Request Syntax¶

curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/<entity> -d {<property>}

Parameters

Parameter	Description
org_id	Organization UUID or organization name
app_id	Application UUID or application name
collection	Name of the collection containing the entity to be updated
uuid\|name	UUID or name of the data entity to be updated
json_object	JSON object with a field for each property to be updated

An entity property to be updated, formatted as a key-value pair. For example:

{"property_1":"value_1", "property_2":"value_2",...}

Example Request/Response¶

Request:

curl -X PUT https://api.usergrid.com/your-org/your-app/items/milk -d '{"price":"4.00", "availability":"in-stock"}'

Response:

{
  "action" : "put",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ {
    "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
    "type" : "item",
    "name" : "milk",
    "created" : 1378405020796,
    "modified" : 1378505705077,
    "availability" : "in-stock",
    "metadata" : {
      "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
    },
    "name" : "milk",
    "price" : "4.00"
  } ],
  "timestamp" : 1378505705050,
  "duration" : 87,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

Updating a sub-property¶

Data entities may contain sets of sub-properties as nested JSON objects. Unlike normal entity properties, however, sub-properties cannot be updated individually. Updating a nested object will cause all sub-properties within it to be overwritten.

For example, if you have a data entity with the following nested object:

Request Syntax¶

curl -X PUT https://api.usergrid.com/<org_id>/<app_id>/<collection>/<uuid|name> -d '{<property> : [{<sub_property>}, {<sub_property>}...]}'

Parameters

Parameter	Description
org_id	Organization UUID or organization name
app_id	Application UUID or application name
collection	Name of the collection containing the entity to be updated
uuid\|name	UUID or name of the data entity to be updated
json_object	JSON object with a field for each property to be updated

Example Request/Response¶

Request:

curl -X PUT https://api.usergrid.com/your-org/your-app/items/milk -d '{"varieties":[{"name":"1%","price":"3.25"},{"name":"whole","price":"4.00"}]}'

Response:

{
  "action" : "put",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ {
    "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4",
    "type" : "item",
    "name" : "milk",
    "created" : 1378405020796,
    "modified" : 1378761459069,
    "availability" : "in-stock",
    "metadata" : {
      "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
    },
    "name" : "milk",
    "uri" : "http://api.usergrid.com/your-org/your-app/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4",
    "varieties" : [ {
      "name" : "1%",
      "price" : "3.25"
    }, {
      "name" : "whole",
      "price" : "4.00"
    } ]
  } ],
  "timestamp" : 1378761459047,
  "duration" : 62,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

Deleting Data Entities¶

This article describes how to delete data entities.

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.

Deleting an entity¶

Request Syntax¶

curl -X DELETE https://api.usergrid.com/<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:

Delete by UUID:

curl -X DELETE "https://api.usergrid.com/your-org/your-app/items/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0"

Delete by ‘name’ property:

curl -X DELETE "https://api.usergrid.com/your-org/your-app/items/milk"

Response:

{
  "action" : "delete",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ {
    "uuid" : "328fe64a-19a0-11e3-8a2a-ebc6f49d1fc4",
    "type" : "item",
    "name" : "milk",
    "created" : 1378766158500,
    "modified" : 1378766158500,
    "metadata" : {
      "path" : "/items/328fe64a-19a0-11e3-8a2a-ebc6f49d1fc4"
    },
    "name" : "milk",
    "price" : "3.25"
  } ],
  "timestamp" : 1378766172016,
  "duration" : 324,
  "organization" : "your-org",
  "applicationName" : "your-app"
}