| # 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](../security-and-auth/authenticating-users-and-application-clients.html) 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](../data-storage/entities.html#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](../security-and-auth/authenticating-users-and-application-clients.html) 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 = <entity_username> |
| |
| All other entities except groups: name = <entity_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](../security-and-auth/authenticating-users-and-application-clients.html) 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](../security-and-auth/authenticating-users-and-application-clients.html) 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" |
| } |
| |
| |
