You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2015/06/25 22:28:35 UTC
[37/51] [partial] incubator-usergrid git commit: Moving website from
SVN to Git.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/updating-collections.md
----------------------------------------------------------------------
diff --git a/website/content/docs/updating-collections.md b/website/content/docs/updating-collections.md
new file mode 100644
index 0000000..50a1ecb
--- /dev/null
+++ b/website/content/docs/updating-collections.md
@@ -0,0 +1,436 @@
+---
+title: Updating Collections
+category: docs
+layout: docs
+---
+
+Updating Collections
+====================
+
+This article describes how to perform batch updates on all entities in a
+collection. Batch updates require the use of a query string in the
+request, which can either specify all entities in the collection or a
+subset of entities for the update to be performed on. For more
+information on queries, see [Basic query syntax](/basic-query-syntax).
+
+**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](/authenticating-users-and-application-clients) for details.
+
+Batch updating entities in a collection
+---------------------------------------
+
+- [cURL](#curl_update_collection)
+- [iOS](#ios_update_collection)
+- [Android](#android_update_collection)
+- [JavaScript (HTML5)](#javascript_update_collection)
+- [Ruby](#ruby_update_collection)
+- [Node.js](#nodejs_update_collection)
+
+### Example Request/Response
+
+#### Request:
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app/items/?ql= -d '{"availability":"in-stock"}'
+
+Note the empty `?ql=` query string.
+
+#### Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### Request Syntax
+
+ curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/?ql= -d {<property>}
+
+Note the empty query string (ql=) appended to the URL.
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| org | Organization UUID or organization |
+| | name |
++--------------------------------------+--------------------------------------+
+| app | Application UUID or application name |
++--------------------------------------+--------------------------------------+
+| collection | Collection UUID or collection name |
++--------------------------------------+--------------------------------------+
+| property | An entity property to be updated, |
+| | formatted as a key-value pair. For |
+| | example: |
+| | |
+| | {"property_1":"value_1", "proper |
+| | ty_2":"value_2",...} |
++--------------------------------------+--------------------------------------+
+
+This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios).
+
+### Example Request/Response
+
+#### Request:
+
+ -(NSString*)updateCollection {
+
+ NSString *url = @"https://api.usergrid.com/your-org/your-app/items/?ql";
+ NSString *op = @"PUT";
+ NSString *opData = @"{\"availability\":\"in-stock\"}"; //we escape the quotes
+
+ //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:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### SDK Method
+
+ (ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData
+
+### Properties
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| url | A fully-formed request url in the |
+| | following format: |
+| | https://api.usergrid.com/<org>/< |
+| | app>/<collection>/?ql= |
+| | |
+| | Note that you must include an empty |
+| | '?ql=' query string at the end of |
+| | the URL |
++--------------------------------------+--------------------------------------+
+| op | The HTTP method - in this case, |
+| | 'PUT' |
++--------------------------------------+--------------------------------------+
+| opData | A JSON-formatted string that |
+| | contains the entity properties to be |
+| | updated |
++--------------------------------------+--------------------------------------+
+
+Updating all entities in a collection is not currently supported by the
+[Apache Usergrid Android SDK](/app-services-sdks#android).
+
+This example uses the [Apache Usergrid JavaScript (HTML5)
+SDK](/app-services-sdks#javascript).
+
+### 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/?ql=", //don't forget to append '/?ql='
+ method:"PUT",
+ body: {"availability":"in-stock"}
+ }
+
+ dataClient.request(options,function (error,response) {
+
+ if (error) {
+ // Error
+ } else {
+ // Success
+ }
+
+ });
+
+
+#### Response:
+
+ Object {action: "put", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"…}
+ action: "put"
+ application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
+ applicationName: "your-app"
+ duration: 92
+ entities: Array[2]
+ 0: Object
+ availability: "in-stock"
+ created: 1378852309294
+ modified: 1378853303215
+ name: "milk"
+ price: "3.25"
+ type: "item"
+ uuid: "c86ffbf0-1a68-11e3-ab22-3713e5fcf9d2"
+ __proto__: Object
+ 1: Object
+ availability: "in-stock"
+ created: 1378852309373
+ modified: 1378853303256
+ name: "bread"
+ price: "4.00"
+ type: "item"
+ uuid: "c87be2da-1a68-11e3-80f4-975f1f8b1f86"
+ __proto__: Object
+ length: 2
+ __proto__: Array[0]
+ organization: "your-org"
+ params: Object
+ path: "/items"
+ timestamp: 1378853303201
+ uri: "http://api.usergrid.com/your-org/your-app/items"
+ __proto__: Object
+
+
+### SDK Method
+
+ request(options, callback)
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| options | A JSON-formatted object containing |
+| | the following properties: |
+| | |
+| | - endpoint: the UUID or name of |
+| | the collection to be updated, |
+| | appended by an empty query |
+| | string in the format: |
+| | \<collection\>/?ql= |
+| | - method: the HTTP method for the |
+| | request – in this case `PUT` |
+| | - body: the body of the request |
+| | that specifies the properties to |
+| | be updated in JSON format |
++--------------------------------------+--------------------------------------+
+| callback | Callback function to handle the API |
+| | response |
++--------------------------------------+--------------------------------------+
+
+This example uses the [Apache Usergrid RubyGem](/app-services-sdks#ruby).
+
+### 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
+ collection = client['items'].collection
+ collection.update_query({availability: 'in-stock'},"")
+ rescue
+ #fail
+ end
+
+
+#### Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### SDK Method
+
+ collection.update_query(properties, query_string)
+
+### Properties
+
+ Parameter Description
+ --------------- --------------------------------------------------------------------------------------------------------------
+ properties JSON-formatted string that contains the entity properties to be updated
+ query\_string A query string that specifies the entities to be updated. Use an empty string (`""`) to update all entities.
+
+The example assumes use of the [Apache Usergrid Node.js
+module](/app-services-sdks#nodejs).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create the Apache Usergrid client object
+ var dataClient = new Usergrid.client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //Specify the options for the request
+ var options = {
+ endpoint:"items/?ql=", //don't forget to append '/?ql='
+ method:"PUT",
+ body: {"availability":"in-stock"}
+ }
+
+ dataClient.request(options,function (error,response) {
+
+ if (error) {
+ //error
+ } else {
+ //success
+ }
+
+ });
+
+
+#### Response:
+
+ { action: 'put',
+ application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
+ params: { ql: [ '' ] },
+ path: '/items',
+ uri: 'http://api.usergrid.com/your-org/your-app/items',
+ entities:
+ [ { uuid: 'c86ffbf0-1a68-11e3-ab22-3713e5fcf9d2',
+ type: 'item',
+ name: 'milk',
+ created: 1378852309294,
+ modified: 1378855073613,
+ availability: 'in-stock' },
+ { uuid: 'c87be2da-1a68-11e3-80f4-975f1f8b1f86',
+ type: 'item',
+ name: 'bread',
+ created: 1378852309373,
+ modified: 1378855073655,
+ availability: 'in-stock' } ],
+ timestamp: 1378855073595,
+ duration: 106,
+ organization: 'your-org',
+ applicationName: 'your-app' }
+
+
+### SDK Method
+
+ request(options,callback);
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| options | A JSON-formatted object containing |
+| | the following properties: |
+| | |
+| | - endpoint: the UUID or name of |
+| | the collection to be updated, |
+| | appended by an empty query |
+| | string in the format: |
+| | \<collection\>/?ql= |
+| | - method: the HTTP method for the |
+| | request, in this case *PUT* |
++--------------------------------------+--------------------------------------+
+| callback | Callback function to handle the API |
+| | response |
++--------------------------------------+--------------------------------------+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/updating-data-entities.md
----------------------------------------------------------------------
diff --git a/website/content/docs/updating-data-entities.md b/website/content/docs/updating-data-entities.md
new file mode 100644
index 0000000..a034a2b
--- /dev/null
+++ b/website/content/docs/updating-data-entities.md
@@ -0,0 +1,1008 @@
+---
+title: Updating Data Entities
+category: docs
+layout: docs
+---
+
+Updating Data Entities
+======================
+
+This article describes how to update entities in your Apache Usergrid
+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](/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](#update_nested) below.
+
+- [cURL](#curl_update_entity)
+- [iOS](#ios_update_entity)
+- [Android](#android_update_entity)
+- [JavaScript (HTML5)](#javascript_update_entity)
+- [Ruby](#ruby_update_entity)
+- [Node.js](#nodejs_update_entity)
+
+### 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"
+ }
+
+### Request Syntax
+
+ curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/<entity> -d {<property>}
+
+### 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 |
++--------------------------------------+--------------------------------------+
+| property | An entity property to be updated, |
+| | formatted as a key-value pair. For |
+| | example: |
+| | |
+| | {"property_1":"value_1", "proper |
+| | ty_2":"value_2",...} |
++--------------------------------------+--------------------------------------+
+
+This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios).
+
+### Example Request/Response
+
+#### Request:
+
+ -(NSString*)updateEntity {
+
+ //UUID of the entity to be updated
+ NSString *entityID = @"f42752aa-08fe-11e3-8268-5bd5fa5f701f";
+
+ //Create an entity object
+ NSMutableDictionary *updatedEntity = [[NSMutableDictionary alloc] init ];
+
+ //Set entity properties to be updated
+ [updatedEntity setObject:@"item" forKey:@"type"]; //Required - entity type
+ [updatedEntity setObject:@"in-stock" forKey:@"availability"];
+ [updatedEntity setObject:@"4.00" 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 updateEntity:entityID entity:updatedEntity];
+
+ @try {
+
+ //success
+
+ }
+ @catch (NSException * e) {
+ //fail
+ }
+
+ }
+
+
+#### 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"
+ }
+
+### SDK Method
+
+ (ApigeeClientResponse *)updateEntity: (NSString *)entityID entity:(NSDictionary *)updatedEntity
+
+### Parameters
+
+ Parameter Description
+ --------------- -------------------------------------------------------------
+ entityID UUID of the entity to be updated
+ updatedEntity NSMutableDictionary containing the properties to be updated
+
+This example uses the [Apache Usergrid Android
+SDK](/app-services-sdks#android).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create client entity
+ String ORGNAME = "your-org";
+ String APPNAME = "your-app";
+ ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME);
+ DataClient dataClient = apigeeClient.getDataClient();
+
+ //Create properties object
+
+ String entityID = "fd0def5a-091c-11e3-a60d-eb644ab154cc";
+
+ Map<String, Object> updatedProperties = new HashMap<String, Object>();
+ updatedProperties.put("type", "item"); //Required
+ updatedProperties.put("availability", "in-stock");
+ updatedProperties.put("price", "4.00");
+
+ //call updateEntityAsync to initiate the asynchronous API call
+ dataClient.updateEntityAsync(entityID, updatedProperties, new ApiResponseCallback() {
+
+ //If updateEntityAsync fails, catch the error
+ @Override
+ public void onException(Exception e) {
+ // Error
+ }
+
+ //If updateEntityAsync 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":"put","application":"f34f4222-a166-11e2-a7f7-02e81adcf3d0","entities":[{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org"},"type":"item","uuid":"5bb76bca-1657-11e3-903f-9ff6c621a7a4","price":"4.00","created":1378405020796,"name":"milk","modified":1378748497900,"availability":"in-stock","metadata":{"path":"/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"}}],"params":{},"path":"/items","rawResponse":"{
+ "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" : 1378748497900,
+ "availability" : "in-stock",
+ "metadata" : {
+ "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ },
+ "name" : "milk",
+ "price" : "4.00"
+ } ],
+ "timestamp" : 1378748497887,
+ "duration" : 80,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+ ","uri":"http://api.usergrid.com/your-org/your-app/items","timestamp":1378748497887,"entityCount":1,"firstEntity":{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org"},"type":"item","uuid":"5bb76bca-1657-11e3-903f-9ff6c621a7a4","price":"4.00","created":1378405020796,"name":"milk","modified":1378748497900,"availability":"in-stock","metadata":{"path":"/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"}},"lastEntity":{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org"},"type":"item","uuid":"5bb76bca-1657-11e3-903f-9ff6c621a7a4","price":"4.00","created":1378405020796,"name":"milk","modified":1378748497900,"availability":"in-stock","metadata":{"path":"/items/5bb76bca-1657-11e3-903f-9f
f6c621a7a4"}},"organization":"your-org","duration":80,"applicationName":"your-app"}
+
+
+### SDK Method
+
+Asynchronous:
+
+ updateEntityAsync(String entityID, Map<String, Object> updatedProperties, ApiResponseCallback callback)
+
+Synchronous:
+
+ updateEntity(String entityID, Map<String, Object> updatedProperties)
+
+### Parameters
+
+ Parameter Description
+ ------------------- ------------------------------------------------------------------------------------
+ entityID UUID of the entity to be updated
+ updatedProperties Map object containing the properties to be updated. A 'type' property is required.
+ callback Callback function (Asynchronous calls only)
+
+This example uses the [Apache Usergrid JavaScript (HTML5)
+SDK](/app-services-sdks#javascript).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create the Apache Usergrid client object
+ var dataClient = new Usergrid.Client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //Specify the UUID of the entity to be updated
+ //and the properties to be updated
+ var properties = {
+ client:dataClient, //Required
+ data:{'type':'item',
+ uuid:'b3aad0a4-f322-11e2-a9c1-999e12039f87', //UUID of the entity to be updated is required
+ price:'4.00',
+ availability:'in-stock'
+ }
+ };
+
+ //Create a new entity object that contains the updated properties
+ var entity = new Usergrid.Entity(properties);
+
+ //Call Entity.save() to initiate the API PUT request
+ entity.save(function (error,response) {
+
+ if (error) {
+ //error
+ } else {
+ //success
+ }
+
+ });
+
+
+#### Response:
+
+ Object {action: "put", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"…}
+ action: "put"
+ application: "f34f4222-a166-11e2-a7f7-02e8sd83f3d0"
+ applicationName: "your-app"
+ duration: 62
+ entities: Array[1]
+ 0: Object
+ created: 1374534114329
+ metadata: Object
+ modified: 1376693371847
+ name: "milk"
+ price: "4.00" //updated
+ availability: "in-stock" //updated
+ varieties: Array[3] //This property was already present
+ type: "item"
+ uuid: "b3aad0a4-f322-11e2-a9c1-999e12039f87"
+ varieties: Array[3]
+ __proto__: Object
+ length: 1
+ __proto__: Array[0]
+ organization: "your-org"
+ params: Object
+ path: "/items"
+ timestamp: 1376693371836
+ uri: "http://api.usergrid.com/your-org/your-app/items"
+
+
+### SDK Method
+
+ Entity.save();
+
+This example uses the [Apache Usergrid RubyGem](/app-services-sdks#ruby).
+
+### 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
+
+ # Specify the name or uuid of the collection and entity to be updated
+ # and the entity properties to be updated
+ entity = client['item']['b3aad0a4-f322-11e2-a9c1-999e12039f87'].entity #entity object
+ entity.price = '4.00'
+ entity.availability = 'in-stock'
+
+ # Call save to initiate the API PUT request
+ entity.save
+
+ rescue
+
+ #fail
+
+ end
+
+
+#### 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"
+ }
+
+### SDK Method
+
+ save
+
+The example assumes use of the [Apache Usergrid Node.js
+module](/app-services-sdks#nodejs).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create the Apache Usergrid client object
+ var dataClient = new Usergrid.client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //Specify the UUID of the entity to be updated
+ //and the properties to be updated
+ var properties = {
+ client:dataClient, //Required
+ data:{'type':'item',
+ uuid:'b3aad0a4-f322-11e2-a9c1-999e12039f87', //UUID of the entity to be updated is required
+ price:'4.00',
+ availability:'in-stock'
+ }
+ };
+
+ //Create a new entity object the contains the updated properties
+ var entity = new Usergrid.entity(properties);
+
+ //Call Entity.save() to initiate the API PUT request
+ entity.save(function (error,response) {
+
+ if (error) {
+ //error
+ } else {
+ //success
+ }
+
+ });
+
+
+### Example - Response
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "b3aad0a4-f322-11e2-a9c1-999e12039f87",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1374534114329,
+ "modified" : 1376695962803,
+ "metadata" : {
+ "path" : "/items/b3aad0a4-f322-11e2-a9c1-999e12039f87"
+ },
+ "name" : "milk",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ } ],
+ "timestamp" : 1376695962790,
+ "duration" : 144,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+
+### SDK Method
+
+ Entity.save();
+
+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:
+
+ "varieties": [
+ {
+ "name": "1%",
+ "price": "3.25",
+ "SKU": "0393847575533445"
+ },
+ {
+ "name": "whole",
+ "price": "3.85",
+ "SKU": "0393394956788445"
+ }
+ ]
+
+
+and you send this update to Apache Usergrid:
+
+ "varieties": [
+ {
+ "name": "2%",
+ "price": "3.00",
+ },
+ {
+ "price": "4.00",
+ }
+ ]
+
+
+this will be the resulting nested object:
+
+ "varieties": [
+ {
+ "name": "2%",
+ "price": "3.00",
+ },
+ {
+ "price": "4.00",
+ }
+ ]
+
+
+- [cURL](#curl_update_subproperty)
+- [iOS](#ios_update_subproperty)
+- [Android](#android_update_subproperty)
+- [JavaScript (HTML5)](#javascript_update_subproperty)
+- [Ruby](#ruby_update_subproperty)
+- [Node.js](#nodejs_update_subproperty)
+
+### 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"
+ }
+
+### 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
+
+ entity\_property The name of the entity property that contains the nested object to be updated
+
+ sub\_property Entity properties of the nested object, as a set of key-value pairs in the format:\
+ *{\<property\_name\> : \<property\_value\>, \<property\_name\> : \<property\_value\> ...}*
+ ---------------------------------------------------------------------------------------------------------------
+
+This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios).
+
+### Example Request/Response
+
+#### Request:
+
+ -(NSString*)updateEntity {
+
+ //UUID of the entity to be updated
+ NSString *entityID = @"f42752aa-08fe-11e3-8268-5bd5fa5f701f";
+
+ //Define our two sub-properties to include in the update
+ NSMutableDictionary *subproperty1 = [[NSMutableDictionary alloc] init];
+ NSMutableDictionary *subproperty2 = [[NSMutableDictionary alloc] init];
+ [subproperty1 setObject:@"1%" forKey:@"name"];
+ [subproperty1 setObject:@"3.25" forKey:@"price"];
+ [subproperty2 setObject:@"whole" forKey:@"name"];
+ [subproperty2 setObject:@"4.00" forKey:@"price"];
+
+ //Put our sub-properties into an NSArray
+ NSArray *subproperties = [[NSArray alloc] initWithObjects:props1,props2, nil];
+
+ //Create an NSMutableDictionary to hold our updates
+ NSMutableDictionary *updatedEntity = [[NSMutableDictionary alloc] init ];
+
+ //Set the properties to be updated
+ [updatedEntity setObject:@"item" forKey:@"type"]; //Required - entity type
+ [updatedEntity setObject:props forKey:@"varieties"];
+
+ //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 updateEntity:entityID entity:updatedEntity];
+
+ @try {
+
+ //success
+
+ }
+ @catch (NSException * e) {
+ //fail
+ }
+
+ }
+
+
+#### 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"
+ }
+
+### SDK Method
+
+ (ApigeeClientResponse *)updateEntity: (NSString *)entityID entity:(NSDictionary *)updatedEntity
+
+### Parameters
+
+ Parameter Description
+ --------------- -------------------------------------------------------
+ entityID UUID of the entity to be updated
+ updatedEntity Entity object containing the properties to be updated
+
+This example uses the [Apache Usergrid Android
+SDK](/app-services-sdks#android).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create client entity
+ String ORGNAME = "your-org";
+ String APPNAME = "your-app";
+ ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME);
+ DataClient dataClient = apigeeClient.getDataClient();
+
+ //UUID of the entity to be updated
+ String entityID = "1ceed6ba-1b13-11e3-a7a6-59ffaee069e1";
+
+ //The object we will pass to the API
+ Map<String,Object> entityUpdates = new HashMap<String,Object>();
+
+ //The objects we will need to setup the sub-properties
+ ArrayList<Map<String,Object>> subPropertyArray = new ArrayList<Map<String,Object>>();
+ Map<String,Object> subProperty1 = new HashMap<String,Object>();
+ Map<String,Object> subProperty2 = new HashMap<String,Object>();
+
+ //First sub-property
+ subProperty1.put("name", "1%");
+ subProperty2.put("price", "3.25");
+
+ //Second sub-property
+ subProperty2.put("name", "whole");
+ subProperty2.put("price", "4.00");
+
+ //Add the sub-properties to the List object
+ subPropertyArray.add(subProperty1);
+ subPropertyArray.add(subProperty2);
+
+ //Now we put it all together
+ entityUpdates.put("type", "item"); //Required
+ entityUpdates.put("varieties", subPropertyArray);
+
+
+ //call updateEntityAsync to initiate the asynchronous API call
+ dataClient.updateEntityAsync(entityID, updatedProperties, new ApiResponseCallback() {
+
+ //If updateEntityAsync fails, catch the error
+ @Override
+ public void onException(Exception e) {
+ // Error
+ }
+
+ //If updateEntityAsync 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":"put","application":"f34f4222-a166-11e2-a7f7-02e81adcf3d0","entities":[{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org"},"type":"item","uuid":"1ceed6ba-1b13-11e3-a7a6-59ffaee069e1","varieties":[{"name":"1%","price":"3.25"},{"name":"whole","price":"4.00"}],"created":1378925465499,"name":"milk","modified":1378936578609,"metadata":{"path":"/items/1ceed6ba-1b13-11e3-a7a6-59ffaee069e1"}}],"params":{},"path":"/items","rawResponse":"{
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "1ceed6ba-1b13-11e3-a7a6-59ffaee069e1",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378925465499,
+ "modified" : 1378936578609,
+ "metadata" : {
+ "path" : "/items/1ceed6ba-1b13-11e3-a7a6-59ffaee069e1"
+ },
+ "name" : "milk",
+ "varieties" : [ {
+ "name" : "1%",
+ "price" : "3.25"
+ }, {
+ "name" : "whole",
+ "price" : "4.00"
+ } ]
+ } ],
+ "timestamp" : 1378936578595,
+ "duration" : 75,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+ ","uri":"http://api.usergrid.com/your-org/your-app/items","timestamp":1378936578595,"entityCount":1,"firstEntity":{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org"},"type":"item","uuid":"1ceed6ba-1b13-11e3-a7a6-59ffaee069e1","varieties":[{"name":"1%","price":"3.25"},{"name":"whole","price":"4.00"}],"created":1378925465499,"name":"milk","modified":1378936578609,"metadata":{"path":"/items/1ceed6ba-1b13-11e3-a7a6-59ffaee069e1"}},"lastEntity":{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org"},"type":"item","uuid":"1ceed6ba-1b13-11e3-a7a6-59ffaee069e1","varieties":[{"name":"1%","price":"3.25"},{"name":"whole","price":"4.00"}],"created":1378925465499,"name":"milk","modified"
:1378936578609,"metadata":{"path":"/items/1ceed6ba-1b13-11e3-a7a6-59ffaee069e1"}},"organization":"your-org","duration":75,"applicationName":"your-app"}
+
+
+### SDK Method
+
+Asynchronous:
+
+ updateEntityAsync(String entityID, Map<String, Object> updatedProperties, ApiResponseCallback callback)
+
+Synchronous:
+
+ updateEntity(String entityID, Map<String, Object> updatedProperties)
+
+### Parameters
+
+ Parameter Description
+ ------------------- ------------------------------------------------------------------------------------
+ entityID UUID of the entity to be updated
+ updatedProperties Map object containing the properties to be updated. A 'type' property is required.
+ callback Callback function (Asynchronous calls only)
+
+This example uses the [Apache Usergrid JavaScript (HTML5)
+SDK](/app-services-sdks#javascript).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create the Apache Usergrid client object
+ var dataClient = new Usergrid.Client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //Specify the UUID of the entity to be updated
+ //and the properties to be updated
+ var properties = {
+ client:dataClient, //Required
+ data:{
+ type:'item',
+ uuid:'b151ddba-0921-11e3-9f60-2ba945ba461f',
+ varieties:[
+ {"name":"3%", "price":"3.25", "SKU":"9384752200033"},
+ {"name":"whole", "price":"4.00", "SKU":"9384752200033"}
+ ]
+ }
+ };
+
+ //Create a new entity object that contains the updated properties
+ var entity = new Usergrid.Entity(properties);
+
+ //Call Entity.save() to initiate the API PUT request
+ entity.save(function (error,response) {
+
+ if (error) {
+ //error
+ } else {
+ //success
+ }
+
+ });
+
+
+#### Response:
+
+ Object {action: "put", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"…}
+ action: "put"
+ application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
+ applicationName: "your-app"
+ duration: 66
+ entities: Array[1]
+ 0: Object
+ availability: "in-stock"
+ created: 1378405020796
+ metadata: Object
+ modified: 1378760239203
+ name: "milk"
+ price: "4.00"
+ type: "item"
+ uri: "http://api.usergrid.com/your-org/your-app/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ uuid: "5bb76bca-1657-11e3-903f-9ff6c621a7a4"
+ varieties: Array[2]
+ 0: Object
+ SKU: "9384752200033"
+ name: "3%"
+ price: "3.25"
+ __proto__: Object
+ 1: Object
+ SKU: "9384752200033"
+ name: "whole"
+ price: "4.00"
+ __proto__: Object
+ length: 2
+ __proto__: Array[0]
+ __proto__: Object
+ length: 1
+ __proto__: Array[0]
+ organization: "your-org"
+ params: Object
+ path: "/items"
+ timestamp: 1378760239191
+ uri: "http://api.usergrid.com/your-org/your-app/items"
+ __proto__: Object
+
+
+### SDK Method
+
+ Entity.save();
+
+This example uses the [Apache Usergrid RubyGem](/app-services-sdks#ruby).
+
+### 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
+
+ # Specify the name or uuid of the collection and entity to be updated
+ # and the entity properties to be updated
+ entity = client['item']['b3aad0a4-f322-11e2-a9c1-999e12039f87'].entity #entity object
+ entity.varieties = [
+ {
+ "name" => "1%",
+ "price" => "3.25",
+ "sku" => "0393847575533445"
+ },{
+ "name" => "whole",
+ "price" => "3.85",
+ "sku" => "0393394956788445"
+ }
+ ]
+
+ # Call save to initiate the API PUT request
+ entity.save
+
+ rescue
+
+ #fail
+
+ end
+
+
+#### Response:
+
+[[nid:11954]
+
+### SDK Method
+
+ save
+
+This example uses the [Apache Usergrid Node.js
+module](/app-services-sdks#nodejs).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create the Apache Usergrid client object
+ var dataClient = new Usergrid.client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //Specify the UUID of the entity to be updated
+ //and the properties to be updated
+
+ var properties = {
+ client:dataClient, //Required
+ data:{
+ type:'item',
+ uuid:'b3aad0a4-f322-11e2-a9c1-999e12039f87', //UUID of the entity to be updated is required
+ varieties : [
+ {
+ "name" : "1%",
+ "price" : "3.25",
+ "sku" : "0393847575533445"
+ },{
+ "name" : "whole",
+ "price" : "3.85",
+ "sku" : "0393394956788445"
+ },{
+ "name" : "skim",
+ "price" : "4.00",
+ "sku" : "0390299933488445"
+ }
+ ]
+ }
+ };
+
+ //Create a new entity object the contains the updated properties
+ var entity = new Usergrid.entity(properties);
+
+ //Call Entity.save() to initiate the API PUT request
+ entity.save(function (error,response) {
+
+ if (error) {
+ //error
+ } else {
+ //success
+ }
+
+ });
+
+
+#### Response:
+
+ { action: 'put',
+ application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
+ params: {},
+ path: '/items',
+ uri: 'http://api.usergrid.com/your-org/your-app/items',
+ entities:
+ [ { uuid: 'b3aad0a4-f322-11e2-a9c1-999e12039f87',
+ type: 'item',
+ created: 1374534114329,
+ modified: 1377039726738,
+ metadata: [Object],
+ varieties: [Object] } ],
+ timestamp: 1377039726724,
+ duration: 75,
+ organization: 'your-org',
+ applicationName: 'your-app' }
+
+
+### SDK Method
+
+ Entity.save();
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/upgrading.md
----------------------------------------------------------------------
diff --git a/website/content/docs/upgrading.md b/website/content/docs/upgrading.md
new file mode 100644
index 0000000..38c560d
--- /dev/null
+++ b/website/content/docs/upgrading.md
@@ -0,0 +1,7 @@
+---
+title: Upgrading from Previous Versions
+category: docs
+layout: docs
+---
+
+If you built and used a previous version of Usergrid, that may be using a different schema, we have an easy built-in tool to audit your Cassandra column family structure and upgrade the dataset as necessary. Once you have pulled, built and launched the new version of Usergrid, just hit [http://localhost:8080/system/database/setup](http://localhost:8080/system/database/setup) to run the upgrade tool.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/uploading-files-and-assets.md
----------------------------------------------------------------------
diff --git a/website/content/docs/uploading-files-and-assets.md b/website/content/docs/uploading-files-and-assets.md
new file mode 100644
index 0000000..d8e8a7b
--- /dev/null
+++ b/website/content/docs/uploading-files-and-assets.md
@@ -0,0 +1,289 @@
+---
+title: Uploading files and assets
+category: docs
+layout: docs
+---
+
+Uploading files and assets
+==========================
+
+**Beta Feature**\
+ Please note that this is currently a beta feature. As a result, some
+functionality may not work as expected.
+
+Using Apache Usergrid APIs, you can store and retrieve files and assets
+that hold data objects such as images, video, and audio content.
+
+Apache Usergrid manages these objects as [Assets](/assets) entities.
+Optionally, you can use [Folder](/folder) entities to organize related
+assets.
+
+**Note:** All binary objects are managed as assets. However, an asset
+does not have to be used for a binary object. For example, assets can be
+used to model a file system.
+
+Creating a folder to hold assets
+--------------------------------
+
+Suppose you have some images that you want to store. Suppose too that
+you want to organize your images in folders. To create a folder, you
+issue a POST request to the folders endpoint. The general format of the
+request is:
+
+ POST /{org-uuid}/{app-uuid}/folders {request body}
+
+The request body must specify the name of the folder, the UUID of the
+owner of the folder, as well as the relative path to the folder.
+
+Here’s how you could create a folder named myfirstfolder to hold some of
+the images:
+
+ POST https://api.usergrid.com/my-org/my-app/folders {"name": "myfirstfolder","owner": "7d1aa429-e978-11e0-8264-005056c00008", "path": "/myfolders/folder1"}
+
+**Note:** Although not shown in the API examples, you need to provide a
+valid access token with each API call. See [Authenticating users and
+application clients](/authenticating-users-and-application-clients) for
+details. You also need to replace my-org with the name of your
+organization, my-app with the name of your application, and the UUID and
+path values as appropriate.
+
+The response to the API request should include the UUID of the created
+folder, for example:
+
+ "uuid": "6640a601-2ac6-11e2-92c3-02e81ae640dc"
+
+You’ll need this UUID to link the folder to assets.
+
+Creating an assets entity
+-------------------------
+
+Assume that one of the images is named my-image.jpg. You can create an
+asset for the image by issuing a POST request to the assets endpoint.
+The general format of the request is:
+
+ POST /{org-uuid}/{app-uuid}/assets {request body}
+
+The request body must specify the UUID of the name of the asset, the
+owner of the asset, as well as the relative path to the asset. For
+example, you can create an asset for the my-image.jpg image like this:
+
+ POST https://api.usergrid.com/my-org/my-app/assets {"name": "my-image.jpg","owner": "7d1aa429-e978-11e0-8264-005056c00008", "path": "/myassets/asset1"}
+
+You can also specify a content-type property for the asset in the
+request body. For example, you can specify "content-type”:”image/jpeg”.
+That content type is then set as a property of the asset. It is also set
+(as specified) in the response header. Specifying the content-type is
+optional. Apache Usergrid can automatically detect the content type of the
+asset when the binary data for the asset is uploaded. It then sets this
+as the content-type property value on the asset.
+
+The response to the API request should include the UUID of the created
+asset, for example:
+
+ "uuid": "9501cda1-2d21-11e2-b4c6-02e81ac5a17b"
+
+You’ll need this UUID when you upload or retrieve the image.
+
+Linking a folder to an asset
+----------------------------
+
+In order to access the asset for the image in the folder, you need to
+link the folder to the asset. You can do that by issuing a POST request
+in the following format:
+
+ POST /{org-uuid}/{app-uuid}/folders/{folder-uuid}/assets/{assets_id}
+
+where {folder-uuid} is the UUID of the folder, and {assets-uuid} is the
+UUID of the assets entity.
+
+Here’s how you could link the folder and the asset you created for the
+my-image.jpg image:
+
+ POST https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b
+
+In the response, you should see the assets entity for the image added to
+the folder:
+
+ {
+ "action": "post",
+ "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+ "params": {},
+ "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+ "uri": "https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+ "entities": [
+ {
+ "uuid": "9501cda1-2d21-11e2-b4c6-02e81ac5a17b",
+ "type": "asset",
+ "name": "my-image.jpg",
+ "created": 1352763303163,
+ "modified": 1352763303163,
+ "metadata": {
+ "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b"
+ },
+ "owner": "5c0c1789-d503-11e1-b36a-12313b01d5c1",
+ "path": "/myassets/asset1"
+ }
+ ],
+ "timestamp": 1352830448045,
+ "duration": 54,
+ "organization": "my-org”,
+ "applicationName": "my-app"
+ }
+
+You can also request a list of the linked contents of the folder like
+this:
+
+ GET https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets
+
+The response should look something like this:
+
+ {
+ "action": "get",
+ "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+ "params": {
+ "_": [
+ "1352830364891"
+ ]
+ },
+ "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+ "uri": "https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+ "entities": [
+ {
+ "uuid": "7bf47435-2ac8-11e2-b4c6-02e81ac5a17b",
+ "type": "asset",
+ "name": "my-image.jpg",
+ "created": 1352505133598,
+ "modified": 1352507245108,
+ "checksum": "8e0cd3866ee20746c99e9a9825f38ad8",
+ "content-length": 11853,
+ "content-type": "image/jpeg",
+ "etag": "\"8e0cd3866ee20746c99e9a9825f38ad8\"",
+ "metadata": {
+ "connecting": {
+ "assets": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/7bf47435-2ac8-11e2-b4c6-02e81ac5a17b/connecting/assets"
+ },
+ "connection": "assets",
+ "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/7bf47435-2ac8-11e2-b4c6-02e81ac5a17b"
+ },
+ "owner": "5c0c1789-d503-11e1-b36a-12313b01d5c1",
+ "path": "my-image"
+ }
+ ],
+ "timestamp": 1352830363797,
+ "duration": 57,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Retrieving an asset
+-------------------
+
+You can retrieve an asset by its UUID. The general form of the request
+is:
+
+ GET /{org-uuid}/{app-uuid}/assets/{asset-uuid}
+
+For example, to retrieve the asset for the my-image.jpg image, you make
+a request like this:
+
+ GET https://api.usergrid.com/my-org/my-app/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b
+
+The response should look something like this:
+
+ {
+ "action": "get",
+ "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+ "params": {
+ "_": [
+ "1352833055831"
+ ]
+ },
+ "path": "/assets",
+ "uri": "https://api.usergrid.com/my-org/my-app/assets",
+ "entities": [
+ {
+ "uuid": "9501cda1-2d21-11e2-b4c6-02e81ac5a17b",
+ "type": "asset",
+ "name": "edhead3.jpg",
+ "created": 1352763303163,
+ "modified": 1352763303163,
+ "metadata": {
+ "connecting": {
+ "assets": "/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b/connecting/assets"
+ },
+ "path": "/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b"
+ },
+ "owner": "5c0c1789-d503-11e1-b36a-12313b01d5c1",
+ "path": "/myassets/asset1"
+ }
+ ],
+ "timestamp": 1352833055408,
+ "duration": 17,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Uploading and retrieving binary data for an asset
+-------------------------------------------------
+
+So far the focus has been on assets entities, which App services uses to
+manage binary objects such as images. But what about the data for those
+objects? You can use Apache Usergrid APIs to upload the data for a binary
+object and retrieve the data.
+
+**Note:** The data for an asset is stored separately from the entity
+itself.
+
+To upload data for an asset, you issue a POST request to the endpoint
+for the asset’s data. The general form of the request is:
+
+ POST /{org-uuid}/{app-uuid}/assets/{asset-uuid}/data {binary-data}
+
+where {binary-data} is the binary data for the asset.
+
+For example, you can upload the binary data for the my-image.jpg image
+asset like this:
+
+ POST https://api.usergrid.com/my-org/my-app/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b/data {binary data}
+
+where {binary-data} is the binary data for the image.
+
+In cURL format, the upload request would look something like this:
+
+ POST --data-binary "@src/resources/my-image.jpg" -H
+ "Content-Type: application/octet-stream"
+ ‘https://api.usergrid.com/my-org/my-app/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b/data’
+
+In the cURL example, the binary data is in a file whose relative path is
+src/resources/my-image.jpg.
+
+**Note:** Currently, a 5 MB limitation exists for the size of the
+uploaded binary data. This limitation is temporary and the allowable
+size of a data upload should increase soon.
+
+To retrieve the data, issue a GET request to the same endpoint, for
+example:
+
+ GET https://api.usergrid.com/my-org/my-app/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b/data
+
+In response, you’ll get the binary data for the asset.
+
+Updating the binary data for an asset
+-------------------------------------
+
+Suppose, you want to update the my-image.jpg image. You can do it by
+replacing the binary data for the asset through a PUT request. Here’s an
+example:
+
+ PUT https://api.usergrid.com/my-org/my-app/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b/data {binary-data}
+
+where {binary-data} is the updated binary data for the image.
+
+In cURL format, the update request would look something like this:
+
+ PUT --data-binary "@src/resources/my-image2.jpg" -H
+ "Content-Type: application/octet-stream"
+ ‘https://api.usergrid.com/my-org/my-app/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b/data’
+
+In the cURL example, the updated binary data is in a file whose relative
+path is src/resources/my-image2.jpg.