You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by ti...@apache.org on 2013/11/18 19:51:22 UTC
svn commit: r1543106 [8/23] - in /incubator/usergrid/site: ./ content/
content/bootstrap/ content/community/ content/css/ content/docs/
content/font/ content/img/ content/img/check_flat/ content/js/
content/static/ layouts/ lib/ lib/helpers/ publish/ p...
Added: incubator/usergrid/site/content/docs/deleting-collections.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/deleting-collections.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/deleting-collections.md (added)
+++ incubator/usergrid/site/content/docs/deleting-collections.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,382 @@
+---
+title: Deleting Collections
+category: docs
+layout: docs
+---
+
+Deleting Collections
+====================
+
+This article describes how to batch delete entities in a collection.
+Batch deletes require the use of a query string in the request, which
+can either specify all entities in the collection or a subset of
+entities to be deleted. For more information on queries, see [Basic
+query syntax](/basic-query-syntax). Currently, collections cannot be
+deleted in Apache Usergrid.
+
+**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 deleting entities in a collection
+---------------------------------------
+
+- [cURL](#curl_delete_collection)
+- [iOS](#ios_delete_collection)
+- [Android](#android_delete_collection)
+- [JavaScript (HTML5)](#javascript_delete_collection)
+- [Ruby](#ruby_delete_collection)
+- [Node.js](#nodejs_delete_collection)
+
+### Example Request/Response
+
+#### Request:
+
+ curl -X DELETE "https://api.usergrid.com/your-org/your-app/items/"
+
+#### Response:
+
+ {
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "53fe3700-0abe-11e3-b1f7-1bd100b8059e",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "created" : 1377129832047,
+ "modified" : 1377129832047,
+ "metadata" : {
+ "path" : "/items/53fe3700-0abe-11e3-b1f7-1bd100b8059e"
+ },
+ "name" : "milk"
+ }, {
+ "uuid" : "5ae1fa7a-0abe-11e3-89ab-6be0003c809b",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "created" : 1377129843607,
+ "modified" : 1377129843607,
+ "metadata" : {
+ "path" : "/items/5ae1fa7a-0abe-11e3-89ab-6be0003c809b"
+ },
+ "name" : "bread"
+ } ],
+ "timestamp" : 1378848117272,
+ "duration" : 12275,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### Request Syntax
+
+ curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/?ql=
+
+Note that you must include an empty query string (?ql=) at the end of
+the URL
+
+### Parameters
+
+ Parameter Description
+ ------------ ----------------------------------------
+ org Organization UUID or organization name
+ app Application UUID or application name
+ collection Collection UUID or collection name
+
+This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios).
+
+### Example Request/Response
+
+#### Request:
+
+ -(NSString*)deleteCollection {
+
+ NSString *url = @"https://api.usergrid.com/your-org/your-app/items/?ql";
+ NSString *op = @"DELETE";
+ NSString *opData = nil;
+
+ //we recommend you call ApigeeClient from your AppDelegate.
+ //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
+ //create an instance of AppDelegate
+ AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate];
+
+ //call createEntity to initiate the API call
+ ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData];
+
+ @try {
+ //success
+ }
+ @catch (NSException * e) {
+ //fail
+ }
+
+ }
+
+
+#### Response:
+
+ {
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "53fe3700-0abe-11e3-b1f7-1bd100b8059e",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "created" : 1377129832047,
+ "modified" : 1377129832047,
+ "metadata" : {
+ "path" : "/items/53fe3700-0abe-11e3-b1f7-1bd100b8059e"
+ },
+ "name" : "milk"
+ }, {
+ "uuid" : "5ae1fa7a-0abe-11e3-89ab-6be0003c809b",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "created" : 1377129843607,
+ "modified" : 1377129843607,
+ "metadata" : {
+ "path" : "/items/5ae1fa7a-0abe-11e3-89ab-6be0003c809b"
+ },
+ "name" : "bread"
+ } ],
+ "timestamp" : 1378848117272,
+ "duration" : 12275,
+ "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 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, |
+| | 'DELETE' |
++--------------------------------------+--------------------------------------+
+| opData | No data is being sent, so the value |
+| | is `nil` |
++--------------------------------------+--------------------------------------+
+
+Currently, deleting all entities in a collection is not supported by the
+[Apache Usergrid SDK for Android](/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:"DELETE",
+ }
+
+ dataClient.request(options,function (error,response) {
+
+ if (error) {
+ // Error
+ } else {
+ // Success
+ }
+
+ });
+
+
+#### Response:
+
+The API will respond with 404 Resource Not Found.
+
+### 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 emptied, |
+| | appended by an empty query |
+| | string in the format: |
+| | \<collection\>/?ql= |
+| | - method: the HTTP method for the |
+| | request, in this case *DELETE* |
++--------------------------------------+--------------------------------------+
+| callback | Callback function to handle the API |
+| | response |
++--------------------------------------+--------------------------------------+
+
+### 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
+ client['item'].delete_query ""
+ rescue
+ #fail
+ end
+
+
+#### Response:
+
+ {
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "53fe3700-0abe-11e3-b1f7-1bd100b8059e",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "created" : 1377129832047,
+ "modified" : 1377129832047,
+ "metadata" : {
+ "path" : "/items/53fe3700-0abe-11e3-b1f7-1bd100b8059e"
+ },
+ "name" : "milk"
+ }, {
+ "uuid" : "5ae1fa7a-0abe-11e3-89ab-6be0003c809b",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "created" : 1377129843607,
+ "modified" : 1377129843607,
+ "metadata" : {
+ "path" : "/items/5ae1fa7a-0abe-11e3-89ab-6be0003c809b"
+ },
+ "name" : "bread"
+ } ],
+ "timestamp" : 1378848117272,
+ "duration" : 12275,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### SDK Method
+
+ delete_query <query_string>
+
+### Properties
+
+ Parameter Description
+ --------------- --------------------------------------------------------------------------------------------------------------------------------
+ query\_string A query string that specifies the entities to be deleted. Use an empty string (`""`) to delete all entities in the collection.
+
+This example uses the [Apache Usergrid Node.js
+module](/app-services-sdks#nodejs).
+
+### 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:"DELETE"
+ }
+
+ dataClient.request(options,function (error,response) {
+
+ if (error) {
+ // Error
+ } else {
+ // Success
+ }
+
+ });
+
+
+#### Response:
+
+ { action: 'delete',
+ application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
+ params: { ql: [ '' ] },
+ path: '/tests',
+ uri: 'http://api.usergrid.com/your-org/your-app/items',
+ entities:
+ [ { uuid: '5eac800a-1a61-11e3-95b8-4f685c4bb3d6',
+ type: 'item',
+ name: 'milk',
+ price: '3.25',
+ created: 1378849125376,
+ modified: 1378849125376,
+ metadata: [Object] },
+ { uuid: '5eb77c8a-1a61-11e3-aae6-3be70698d378',
+ type: 'item',
+ name: 'bread',
+ price: '4.00',
+ created: 1378849125448,
+ modified: 1378849125448,
+ metadata: [Object] } ],
+ timestamp: 1378849137959,
+ duration: 648,
+ organization: 'your-org',
+ applicationName: 'your-app' }
+
+
+### SDK Method
+
+ entity.destroy()
+
+### Parameters
+
+ Parameter Description
+ ----------- ----------------------------------------------
+ callback Callback function to handle the API response
+
+Â
Added: incubator/usergrid/site/content/docs/deleting-data-entities.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/deleting-data-entities.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/deleting-data-entities.md (added)
+++ incubator/usergrid/site/content/docs/deleting-data-entities.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,394 @@
+---
+title: Deleting Data Entities
+category: docs
+layout: docs
+---
+
+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](/authenticating-users-and-application-clients) for details.
+
+Deleting an entity
+------------------
+
+- [cURL](#curl_delete_entity)
+- [iOS](#ios_delete_entity)
+- [Android](#android_delete_entity)
+- [JavaScript (HTML5)](#javascript_delete_entity)
+- [Ruby](#ruby_delete_entity)
+- [Node.js](#nodejs_delete_entity)
+
+### 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"
+ }
+
+### 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
+
+This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios).
+
+### Example Request/Response
+
+#### Request:
+
+ -(NSString*)deleteEntity {
+
+ //specify the entity type to be deleted
+ NSString *type = @"item";
+
+ //specify the uuid or name of the entity to be deleted
+ NSString *entityId = @"milk";
+
+ //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 removeEntity:type entityID:entityId];
+
+ @try {
+ //success
+ }
+ @catch (NSException * e) {
+ //fail
+ }
+
+ }
+
+
+
+#### 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"
+ }
+
+### SDK Method
+
+ (ApigeeClientResponse *)removeEntity: (NSString *)type entityID:(NSString *)entityID
+
+### Properties
+
+ Parameter Description
+ ----------- ----------------------------------------------
+ type The entity type being deleted
+ entityID The UUID or name of the entity to be removed
+
+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();
+
+ String type = "item"; //entity type to be retrieved
+ String uuid = "b3aad0a4-f322-11e2-a9c1-999e12039f87";
+
+ //call removeEntityAsync to initiate the asynchronous API call
+ dataClient.removeEntityAsync(type, uuid, new ApiResponseCallback() {
+
+ //If removeEntityAsync fails, catch the error
+ @Override
+ public void onException(Exception e) {
+ // Error
+ }
+
+ //If removeEntityAsync 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":"delete","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":"d1511d7a-19a1-11e3-b02b-cd5b309a29fa","created":1378766854343,"name":"milk","modified":1378766854343,"metadata":{"path":"/items/d1511d7a-19a1-11e3-b02b-cd5b309a29fa"}}],"params":{},"path":"/items","rawResponse":"{
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "d1511d7a-19a1-11e3-b02b-cd5b309a29fa",
+ "type" : "item",
+ "name" : "milk",
+ "created" : 1378766854343,
+ "modified" : 1378766854343,
+ "metadata" : {
+ "path" : "/items/d1511d7a-19a1-11e3-b02b-cd5b309a29fa"
+ },
+ "name" : "milk",
+ "price" : "3.25"
+ } ],
+ "timestamp" : 1378767852615,
+ "duration" : 276,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+ ","uri":"http://api.usergrid.com/your-org/your-app/items","timestamp":1378767852615,"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":"d1511d7a-19a1-11e3-b02b-cd5b309a29fa","created":1378766854343,"name":"milk","modified":1378766854343,"metadata":{"path":"/items/d1511d7a-19a1-11e3-b02b-cd5b309a29fa"}},"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":"d1511d7a-19a1-11e3-b02b-cd5b309a29fa","created":1378766854343,"name":"milk","price" : "3.25","modified":1378766854343,"metadata":{"path":"/items/d1511d7a-19a1-11e3-b02b-cd5b309a29fa"}},"organization":"your-org","duration":276,"applicati
onName":"your-app"}
+
+
+### SDK Method
+
+ removeEntity(String entityType, String entityID)
+
+### Properties
+
+ Parameter Description
+ ------------ ----------------------------------------------
+ entityType The entity type of the entity to be deleted
+ entityID The UUID or name of the entity to be deleted
+
+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'
+ });
+
+ //specify the properties of the entity to be deleted
+ //type is required. UUID or name of the entity to be deleted is also required
+ var properties = {
+ client:client,
+ data:{'type':'item',
+ uuid:'39d25cca-03ad-11e3-a25d-71468ad53e11'
+ }
+ };
+
+ //create the entity object
+ var entity = new Usergrid.Entity(properties);
+
+ //call destroy() to initiate the API DELETE request
+ entity.destroy(function (error) {
+
+ if (error) {
+ // Error
+ } else {
+ // Success
+ }
+
+ });
+
+
+#### Response:
+
+The API will respond with 404 Resource Not Found.
+
+### SDK Method
+
+ entity.destroy(callback)
+
+### Parameters
+
+ Parameter Description
+ ----------- ----------------------------------------------
+ callback Callback function to handle the API response
+
+### 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
+ client['items']['milk'].entity.delete
+ rescue
+ #fail
+ end
+
+
+#### 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"
+ }
+
+### SDK Method
+
+ delete
+
+This example uses the [Apache Usergrid Node.js
+module](/app-services-sdks#nodejs).
+
+### Example Request/Response
+
+#### Request:
+
+ //create the basic client object
+ var dataClient = new Usergrid.client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //specify the properties of the entity to be deleted
+ //type is required. UUID or name of the entity to be deleted is also required
+ var properties = {
+ client:dataClient,
+ data:{
+ 'type':'item',
+ 'uuid':'39d25cca-03ad-11e3-a25d-71468ad53e11'
+ }
+ };
+
+ //create the entity object
+ var entity = new Usergrid.entity(properties);
+
+ //call destroy() to initiate the API DELETE request
+ entity.destroy(function (error) {
+
+ if (error) {
+ // Error
+ } else {
+ // Success
+ }
+
+ });
+
+
+#### Response:
+
+ { action: 'delete',
+ application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
+ params: {},
+ path: '/items',
+ uri: 'http://api.usergrid.com/your-org/your-app/items',
+ entities:
+ [ { uuid: 'f97c35ea-1a5b-11e3-b8a1-6f428da9ad88',
+ type: 'item',
+ name: 'milk',
+ price: '3.25',
+ created: 1378846808126,
+ modified: 1378846808126,
+ metadata: [Object] } ],
+ timestamp: 1378847145757,
+ duration: 285,
+ organization: 'your-org',
+ applicationName: 'your-app' }
+
+
+### SDK Method
+
+ entity.destroy(callback)
+
+### Parameters
+
+ Parameter Description
+ ----------- ----------------------------------------------
+ callback Callback function to handle the API response
+
+Â
Added: incubator/usergrid/site/content/docs/device.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/device.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/device.md (added)
+++ incubator/usergrid/site/content/docs/device.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,41 @@
+---
+title: Device
+category: docs
+layout: docs
+---
+
+Device
+======
+
+Using App services APIs you can create, retrieve, update, delete, and
+query device entities. See You do not have access to view this node for
+descriptions of these APIs.
+
+Device properties
+-----------------
+
+The following are the system-defined properties for device entities. You
+can create application-specific properties for a device entity in
+addition to the system-defined properties. The system-defined properties
+are reserved. You cannot use these names to create other properties for
+a device entity. In addition the devices name is reserved for the
+devices collection â you can't use it to name another collection.
+
+ Property Type Description
+ ---------- -------- ---------------------------------------------------------------------------------
+ uuid UUID Entity unique ID
+ type string Entity type (e.g., device)
+ created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+ modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+ name string Device name (mandatory)
+
+Associated collection property
+------------------------------
+
+Devices have the following associated collection.
+
+ Collection Type Description
+ ------------ ------ -----------------------------------------------
+ users user Collection of users to which a device belongs
+
+Â
Added: incubator/usergrid/site/content/docs/displaying-app-services-api-calls-curl-commands.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/displaying-app-services-api-calls-curl-commands.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/displaying-app-services-api-calls-curl-commands.md (added)
+++ incubator/usergrid/site/content/docs/displaying-app-services-api-calls-curl-commands.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,74 @@
+---
+title: Displaying Apache Usergrid API calls as Curl commands
+category: docs
+layout: docs
+---
+
+Displaying Apache Usergrid API calls as Curl commands
+==================================================
+
+Â
+
+If you use a web application, such as the JavaScript (HTML 5) version of
+Messagee (see [HTML 5 example - Messagee](/html-5-example-messagee)),
+you can easily see the equivalent Curl syntax for each API call that the
+web application makes. The calls are displayed in the console area of
+any of the following browsers: Â Chrome, Internet Explorer (in the
+debugger), Firefox (in Firebug), and Safari.
+
+This is possible because web applications such as the JavaScript version
+of Message takes advantage of a JavaScript SDK provied by Apigee (see
+[HTML5/JavaScript SDK](/html5javascript-sdk))Â to issue Apache Usergrid API
+calls. The SDK automatically translates each API call into a Curl
+command, which is displayed in the console. If you use any web
+application that is built on the JavaScript SDK, you can view the
+applications API's calls in Curl syntax.
+
+The [admin portal](http://apigee.com/usergrid/)Â is another example of a
+web application that is built on the JavaScript SDK and issues App
+Services API calls from JavaScript. When a user clicks a button in the
+admin portal, such as âUsersâ, the admin portal makes an API request to
+retrieve the appropriate data. In addition, the JavaScript SDK in the
+web application automatically translates the API call into the following
+Curl command:
+
+ curl -X GET "https://api.usergrid.com/edort1/sandbox/users?ql=order%20by%20usernameâ
+
+The request retrieves the users in the application and orders the result
+by username.
+
+If you turn on the JavaScript console, hereâs what it displays for the
+call. This example shows the JavaScript console display in the Chrome
+browser. You can turn on the JavaScript console in Chrome by clicking
+the âwrenchâ button (customize and control Chrome) and then selecting
+Tools \> JavaScript console.Â
+
+
+
+Notice that in addition to displaying the API call in Curl syntax, the
+console displays the time to retrieve the user entities.
+
+To display the JavaScript console in Internet Explorer, you need to turn
+on the debugger. You do that by selecting F12 developer tools in the
+tools menu. Hereâs what the Curl version of the API call looks like in
+Internet Explorerâs console.
+
+
+
+Hereâs what the curl version of the API call looks like in Firefoxâs
+JavaScript console.
+
+
+
+You need to have the [Firebug tool](http://getfirebug.com/)Â installed
+and enabled in your Firefox browser to view the curl commands in the
+console.
+
+And hereâs what the API call looks like in the Safari console. The
+console is part of Safariâs Web Inspector tool
+([https://developer.apple.com/technologies/safari/developer-tools.html](https://developer.apple.com/technologies/safari/developer-tools.html)).
+
+
Added: incubator/usergrid/site/content/docs/entity-relationships.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/entity-relationships.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/entity-relationships.md (added)
+++ incubator/usergrid/site/content/docs/entity-relationships.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,107 @@
+---
+title: Entity relationships
+category: docs
+layout: docs
+---
+
+Entity relationships
+====================
+
+Creating connections between entities
+-------------------------------------
+
+One of the most useful features of App services is the ability to create
+connections between entities. A simple example of this is the
+Twitter-like use of *following*, where one user forms a connection with
+another by subscribing to any tweets they post. [Messagee
+Example](/messagee-example) walks you through an example of following
+other users in our sample app, *Messagee*. Here is the basic format:
+
+ POST https://api.usergrid.com/my-org/my-app/users/fred/following/users/barney
+
+This API call results in two users, Fred and Barney, linked with a
+connection where Fred is following Barney.
+
+If you create a *following* connection between two users, Apache Usergrid
+automatically creates a virtual connection called *followers* that
+mirrors the *following* connection. In other words, if you create a
+connection where Fred is following Barney, Apache Usergrid automatically
+creates a virtual connection where Fred is a follower of Barney.
+
+Note that there is no mirror connection established. Apache Usergrid only
+creates a mirror connection when you create a *following* connection. It
+does not create a mirror connection for other verbs such as likes.
+
+You can see all the users that Fred is following, in this case only
+Barney, by making the following API call:
+
+ GET https://api.usergrid.com/my-org/my-app/users/fred/following
+
+You can see all of barneyâs followers, in this case only Fred, by making
+the following API call:
+
+ GET https://api.usergrid.com/my-org/my-app/users/barney/followers
+
+The *followers* connection is a virtual connection because you canât use
+it to link two entities. In other words, you canât make fred a follower
+of barney by using a *followers* connection. Â **This is wrong:**
+
+ POST https://api.usergrid.com/my-org/my-app/users/barney/followers/users/fred
+
+To create a *following* connection with the users switched, so that
+Barney is following Fred, do this:
+
+ POST https://api.usergrid.com/my-org/my-app/users/barney/following/users/fred
+
+You can now see Fredâs followers (only Barney) by making the following
+call:
+
+ GET https://api.usergrid.com/my-org/my-app/users/fred/followers
+
+Creating other connections
+--------------------------
+
+You can extend this connection structure to create connections using any
+"verb" that can link two entities. For example, you could use likes to
+denote a connection between a user and his dog. First, create a dogs
+collection:
+
+ POST https://api.usergrid.com/my-org/my-app/dogs
+
+Then populate this collection with a new dog named Dino:
+
+ POST https://api.usergrid.com/my-org/my-app/dogs {"name" : "dino"}
+
+Then create a likes connection between Fred and his dog Dino:
+
+ POST https://api.usergrid.com/my-org/my-app/users/fred/likes/dogs/dino
+
+Getting connections
+-------------------
+
+### Get all connections for an entity
+
+To get a list that only contains the connections, do a GET on the
+connections sub-property of the entity:
+
+ GET https://api.usergrid.com/my-org/my-app/users/fred/connections
+
+### Get information on a specific connection type
+
+To get a list of users who like Fred:
+
+ GET https://api.usergrid.com/my-org/my-app/users/fred/connecting/likes
+
+To get a list of all dogs that Fred likes:
+
+ GET https://api.usergrid.com/my-org/my-app/users/fred/likes/dog
+
+Deleting a connection
+---------------------
+
+You can delete a connection in a way similar to creating one. Just
+replace the POST method with the DELETE method. For example, you can
+delete the connection between fred and barney with the following API
+call:
+
+ DELETE https://api.usergrid.com/my-org/my-app/users/fred/following/barney
Added: incubator/usergrid/site/content/docs/events-and-counters.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/events-and-counters.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/events-and-counters.md (added)
+++ incubator/usergrid/site/content/docs/events-and-counters.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,405 @@
+---
+title: Events and counters
+category: docs
+layout: docs
+---
+
+Events and counters
+===================
+
+**Beta Feature**\
+\
+ Please note that this is currently a beta feature. As a result, some
+functionality may not work as expected.
+
+
+Events are typically used for application logging. For example, they
+could be used to log error messages that a system administrator might
+review at a later time. The event mechanism is optimized to handle large
+numbers of events, so it is an ideal mechanism for logging in your
+application.
+
+You can link events to specific users, groups, or custom-defined
+categories. When created with these links, events offer a powerful tool
+for running highly targeted, custom reports.
+
+Events are also the primary way to store custom counter data for
+analytics. See Counters (below) for further details.
+
+**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.
+
+Using App services APIs you can create an event.
+
+Creating a new event
+--------------------
+
+Use the POST method to create a new event in the events collection.
+
+### Request URI
+
+POST /{org\_id}/{app\_id}/events {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 |
++--------------------------------------+--------------------------------------+
+| request body | One or more sets of event |
+| | properties. You must provide a |
+| | timestamp property, but if you set |
+| | it to 0 it is assigned by the |
+| | system. |
+| | |
+| | { |
+| | "timestamp":0, |
+| | Â Â "category" : "advertising", |
+| | Â Â "counters" : { |
+| | "ad_clicks" : 5 |
+| | Â Â } |
+| | } |
++--------------------------------------+--------------------------------------+
+
+### Example - Request
+
+- [cURL](#curl_create_event)
+- [JavaScript (HTML5)](#javascript_create_event)
+- [Ruby](#ruby_create_event)
+- [Node.js](#nodejs_create_event)
+
+<!-- -->
+
+ curl -X POST "https://api.usergrid.com/my-org/my-app/events" -d '{"timestamp":0, "category" : "advertising", "counters" : {"ad_clicks" : 5}}'
+
+The example assumes use of the [JavaScript (HTML5)
+SDK](https://github.com/apigee/usergrid-javascript-sdk).
+
+ var options = {
+ method:'POST',
+ endpoint:'events',
+ body:{timestamp:0, category:'advertising', counters:{ad_clicks : 5}}
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error
+ } else {
+ //success - data will contain raw results from API call
+ }
+ });
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+ app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+ result = app.create_event timestamp: '0', category: 'advertising', counters: { ad_clicks: 5 }
+ mynewevent = result.entity
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'POST',
+ endpoint:'events',
+ body:{timestamp:0, category:'advertising', counters:{ad_clicks : 5}}
+ };
+ 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-22000a1c4e22",
+ Â Â Â Â Â Â "params": {},
+ Â Â Â Â Â Â "path": "/events",
+ Â Â Â Â Â Â "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/events",
+ Â Â Â Â Â Â "entities": [
+ Â Â Â Â Â Â Â Â {
+ Â Â Â Â Â Â Â Â Â Â "uuid": "ce07ea3c-68b5-11e1-a586-9227e40e3559",
+ Â Â Â Â Â Â Â Â Â Â "type": "event",
+ Â Â Â Â Â Â Â Â Â Â "created": 1331166585282,
+ Â Â Â Â Â Â Â Â Â Â "modified": 1331166585282,
+ Â Â Â Â Â Â Â Â Â Â "counters": {
+ Â Â Â Â Â Â Â Â Â Â Â Â "ad_clicks": 5
+ Â Â Â Â Â Â Â Â Â Â },
+ Â Â Â Â Â Â Â Â Â Â "metadata": {
+ Â Â Â Â Â Â Â Â Â Â Â Â "path": "/events/ce07ea3c-68b5-11e1-a586-9227e40e3559"
+ Â Â Â Â Â Â Â Â Â Â },
+ Â Â Â Â Â Â Â Â Â Â "timestamp": 1331166585282
+ Â Â Â Â Â Â Â Â }
+ Â Â Â Â Â Â ],
+ Â Â Â Â Â Â "timestamp": 1331166585018,
+ Â Â Â Â Â Â "duration": 919,
+ Â Â Â Â Â Â "organization": "my-org",
+ Â Â Â Â Â Â "applicationName": "my-app"
+ }
+
+Event properties
+----------------
+
+You can pass various system-defined properties for an event. For
+example, you can specify a user property, with a uuid as its value. This
+will link the event to the user and can be used to query against the
+events queue (see Categorization below). The same is true for the group
+property. Pass it with a uuid as the value and the event will be linked
+to the group. To include a uuid of a user or group, add the uuid to the
+request body, for example:
+
+ POST https://api.usergrid.com/my-org/my-app/events {"timestamp":0, "category" : "advertising", "counters" :Â Â {"ad_clicks" : 5},"user" : "1234891-477d-11e1-b2bd-22005a1c4e22", "group" : "75577d891-347d-2231-b5bd-23400a1c4e22"}
+
+The response body would look something like this:
+
+ {
+ Â "action": "post",
+ Â "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ Â "params": {},
+ Â "path": "/events",
+ Â "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/events",
+ Â "entities": [
+ Â Â Â {
+ Â Â Â Â Â "uuid": "ce07ea3c-68b5-11e1-a586-9227e40e3559",
+ Â Â Â Â Â "user": "1234891-477d-11e1-b2bd-22005a1c4e22",
+ Â Â Â Â Â "group": "75577d891-347d-2231-b5bd-23400a1c4e22",
+ Â Â Â Â Â "type": "event",
+ Â Â Â Â Â "created": 1331166585282,
+ Â Â Â Â Â "modified": 1331166585282,
+ Â Â Â Â Â "counters": {
+ Â Â Â Â Â Â Â "ad_clicks": 5
+ Â Â Â Â Â },
+ Â Â Â Â Â "metadata": {
+ Â Â Â Â Â Â Â "path": "/events/ce07ea3c-68b5-11e1-a586-9227e40e3559"
+ Â Â Â Â Â },
+ Â Â Â Â Â "timestamp": 1331166585282
+ Â Â Â }
+ Â ],
+ Â "timestamp": 1331166585018,
+ Â "duration": 919,
+ Â "organization": "my-org",
+ Â "applicationName": "my-app"
+ }
+
+You can also create application-specific event properties in addition to
+these predefined properties. The system-defined properties are reserved.
+You cannot use these names to create other properties for an event
+entity. In addition the events name is reserved for the events
+collection â you can't use it to name another collection.
+
+The System-defined properties are as follows:
+
+ Property Type Description
+ ----------- -------- -------------------------------------------------------------------------------------------
+ uuid UUID Eventâs unique entity ID
+ type String "event"
+ created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+ modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+ timestamp long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of application event (mandatory)
+ user UUID UUID of application user that posted the event
+ group UUID UUID of application group that posted the event
+ category string Category used for organizing similar events
+ counters map Counter used for tracking number of similar events
+ message string Message describing event
+
+### Categorizing events
+
+As mentioned previously, you can link an event to a user or a group.
+This enables you to categorize and qualify event data for use in
+tracking and analysis. For example, linking events to users and groups,
+enables you to track how often people use a feature. Not only can you
+determine the total number of users that used the feature, but also
+which groups contain users that made the most use of the feature. Or,
+you could provide a location with the event, so you could see how often
+a feature was used by people in San Francisco versus Los Angeles.
+
+Counters
+--------
+
+User-defined counters are used in conjunction with events to keep
+statistics on many aspects of an application. User-defined counters are
+JSON objects that are added to events when they are posted. The act of
+posting an event increments the counter. Once created, user-defined
+counters can be used to get reports.
+
+**Note:** It may take up to 30 seconds for a counter to be updated.
+
+### User-Defined Counters
+
+With Apache Usergrid, you can define your own counters. Some of the things
+that you might track with a user-defined counter are:
+
+- How many times people click on the help button in your application.
+- How many times your game is played each day.
+- How many times your banner ads are clicked each day.
+
+You can choose any name for a user-defined counter. For example, the
+counter for the help button might be named âhelp\_buttonâ or
+âhelp\_button\_clicksâ.
+
+To create a user-defined counter, you post to the events collection and
+specify the name and increment value of the counter in the request body.
+The increment value is the value that the counter is incremented by for
+each tracked event. An increment value of 1, means that the counter is
+increment by 1 for each tracked event. You could also specify a higher
+increment value, such as 15, which would increment the value by that
+number, or a negative number, which would decrement the value. Â You can
+also reset the value of the counter, by specifying an increment value of
+0.
+
+When a counter is incremented by an event, there will be a 20-30 second
+delay between when the event is posted and when the counter is
+incremented.Â
+
+As an example, here's how to create a user-defined counter named
+âbutton\_clicksâ with an increment value of 1:
+
+ POST https://api.usergrid.com/my-org/my-app/events {"counters" : {"button_clicks" : 1},"timestamp" : "0"}
+
+The response body would look something like this:
+
+ {
+ Â Â Â "action": "post",
+ Â Â Â "path": "/events",
+ Â Â Â "uri": "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/events",
+ Â Â Â "entities": [
+ Â Â Â Â Â Â Â {
+ Â Â Â Â Â Â Â Â Â Â Â "uuid": "39d41c46-d8e4-11e0-bcc1-12313f0204bb",
+ Â Â Â Â Â Â Â Â Â Â Â "type": "event",
+ Â Â Â Â Â Â Â Â Â Â Â "timestamp": 1315353555546016,
+ Â Â Â Â Â Â Â Â Â Â Â "category":"advertising",
+ Â Â Â Â Â Â Â Â Â Â Â "counters": {
+ Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â "button_clicks": 1
+ Â Â Â Â Â Â Â Â Â Â Â },
+ Â Â Â Â Â Â Â Â Â Â Â "created": 1315353555546016,
+ Â Â Â Â Â Â Â Â Â Â Â "modified": 1315353555546016,
+ Â Â Â Â Â Â Â Â Â Â Â "metadata": {
+ Â Â Â Â Â Â Â Â Â Â Â "path": "/events/39d41c46-d8e4-11e0-bcc1-12313f0204bb"
+ Â Â Â Â Â Â Â Â Â Â Â }
+ Â Â Â Â Â Â Â }
+ Â Â Â ],
+ Â Â Â "timestamp": 1315353555537,
+ Â Â Â "duration": 110,
+ Â Â Â "organization": "my-org",
+ Â Â Â "applicationName": "my-app"
+ }
+
+### Counter hierarchy
+
+Counters are hierarchical in their structure and in the way they are
+incremented. Each level of the hierarchy is separated by the dot â.â
+operator. The hierarchical structure can be useful if you want to store
+or view statistics in a hierarchical way. For example, suppose you want
+to log errors that your app generates. One way to do this, is to fire an
+event every time an error occurs, by creating a counter called âerrorsâ.
+However, you can get more detail by adding additional parameters to the
+counter. Imagine that you want to track errors in a specific module and
+function within that module, say module\_1, function\_1, you could use a
+counter like this:
+
+errors.module\_1.function\_1
+
+And then for a different function in the same module:
+
+errors.module\_1.function\_2
+
+And then for a different function in a different module:
+
+errors.module\_2.function\_3
+
+If each of the preceding examples were called once, the resulting values
+would be:
+
+errors = 3\
+\
+ errors.module\_1 = 2\
+\
+ errors.module\_1.function\_1 = 1\
+\
+ errors.module\_1.function\_2 = 1\
+\
+ errors.module\_2 = 1\
+\
+ errors.module\_2.function\_3 = 1
+
+This tells you that there were 3 errors in the application, with 2 of
+those errors in module\_1. You can then drill down further to see errors
+in specific functions.
+
+### Using counters in time series queries
+
+Knowing the value of a counter is useful. However, you often need to
+know how the value varies over time. Fortunately, the API provides a
+method for you to view this data over any time interval or level of
+granularity.
+
+For example, letâs say youâre incrementing a counter every time someone
+launches your application. You might be interested in which days of the
+week the application sees the most usage. Using the API, you can examine
+the counter over a set of weeks, with the data split into daily
+intervals. Using this information, you can see which are your peak days
+of usage. You can also view usage across a single day, so you can see if
+your application is used more in the mornings or the evenings. For
+business reporting, you may be more interested in monthly reporting.
+
+Note that the system is able to provide you with the report data as you
+need it. The data is maintained in real-time so it can be viewed
+instantly.
+
+### Retrieving counter data
+
+To retrieve counter data, you issue a GET request to the /counters
+endpoint. This is a special, built-in collection that gives you access
+to all the counters currently in the system. The API also provides a
+number of parameters that you can use to search for counter data, as
+follows:
+
+ Parameter Type Description
+ ------------- ------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ start\_time An [Epoch(Unix)](http://en.wikipedia.org/wiki/Unix_time) timestamp in milliseconds The beginning of the time period to search
+ end\_time An [Epoch(Unix)](http://en.wikipedia.org/wiki/Unix_time) timestamp in milliseconds The end of the time period to search
+ counter string The name of a specific counter to search. You can specify more than one counter in a query (for example, counter=counter1&counter=counter2...)
+ resolution string The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days. Possible values are all, minute, five\_minutes, half\_hour, hour, six\_day, day, week, and month.
+
+For example, to retrieve a time range of values, with a granularity of
+"day", for a counter called "button\_clicks", the GET request would look
+like this:
+
+ GET /my-org/my-app/counters?start_time=1315119600000&end_time=1315724400000&resolution=day&counter=button_clicks
+
+The response body would look something like this:
+
+ {
+ action: "get",
+ uri: "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/counters",
+ timestamp: 1315354369272,
+ duration: 28,
+ counters: [
+ {
+ name: "button_clicks",
+ values: [
+ {
+ value: 2
+ timestamp: 1315180800000
+ },
+ {
+ value: 1
+ timestamp: 1315267200000
+ },
+ {
+ value: 1
+ timestamp: 1315353600000
+ }
+ ]
+ }
+ ]
+ }
Added: incubator/usergrid/site/content/docs/facebook-sign.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/facebook-sign.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/facebook-sign.md (added)
+++ incubator/usergrid/site/content/docs/facebook-sign.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,232 @@
+---
+title: Facebook sign in
+category: docs
+layout: docs
+---
+
+Facebook sign in
+================
+
+You can authenticate your Apache Usergrid requests by logging into
+Facebook. To access Apache Usergrid resources, you need to provide an
+access token with each request (unless you use the sandbox app). You can
+get an access token by connecting to an appropriate web service endpoint
+and providing the correct client credentials â this is further described
+in [Authenticating users and application
+clients](/authenticating-users-and-application-clients). However, you
+can also obtain an access token by logging into Facebook.
+
+To enable authentication to Apache Usergrid through Facebook, do the
+following in your app:
+
+1. Make a login call to the Facebook API (do this using the [Facebook
+ SDK](https://developers.facebook.com/docs/sdks/) or
+ [API](https://developers.facebook.com/docs/facebook-login/)). If the
+ login succeeds, a Facebook access token is returned.
+2. Send the Facebook access token to Apache Usergrid. If the Facebook
+ access token is valid and the user does not already exist in App
+ Services, Apache Usergrid provisions a new Apache Usergrid user. It also
+ returns an Apache Usergrid access token, which you can use for
+ subsequent Apache Usergrid API calls. Behind the scenes, Apache Usergrid
+ uses the Facebook access token to retrieve the user's profile
+ information from Facebook.
+
+ If the Facebook access token is invalid, Facebook returns an OAuth
+ authentication error, and the login does not succeed.
+
+The request to authenticate to Apache Usergrid using a Facebook access
+token is:
+
+ GET https://api.usergrid.com/{my_org}/{my_app}/auth/facebook?fb_access_token={fb_access_token}
+
+where:
+
+{my\_org} is the organization UUID or organization name.\
+{my\_app} is the application UUID or application name.\
+{fb\_access\_token} is the Facebook access token.
+
+Facebook login example
+----------------------
+
+The [Facebook technical guides for
+login](https://developers.facebook.com/docs/technical-guides/login/)
+present detailed information on how to add Facebook login to your app.
+Instructions are provided for JavaScript, iOS, and Android.
+
+In brief, here are the steps for JavaScript. You can see these steps
+implemented in the Facebook login example packaged with the JavaScript
+SDK for Apache Usergrid (which you can download in
+[ZIP](https://github.com/apigee/usergrid-javascript-sdk/archive/master.zip)
+format or
+[tar.gz](https://github.com/apigee/usergrid-javascript-sdk/archive/master.tar.gz)
+format). The Facebook login example is in the /examples/facebook
+directory of the extracted download. The code example snippets shown
+below are taken from the Facebook login example.
+
+### Step 1: Create a Facebook app
+
+Create a new app on the [Facebook App
+Dashboard](https://developers.facebook.com/apps/). Enter your app's
+basic information. Once created, note the app ID shown at the top of the
+dashboard page.
+
+### Step 2: Invoke the Facebook OAuth dialog
+
+Invoke the Facebook OAuth Dialog. To do that, redirect the user's
+browser to a URL by inserting the following Javascript code after the
+opening \<body\> tag in your appâs HTML file:
+
+ https://www.facebook.com/dialog/oauth/?
+ client_id={YOUR_APP_ID}
+ &redirect_uri={YOUR_REDIRECT_URL}
+ &state={YOUR_STATE_VALUE}
+ &scope={COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES}
+ &response_type={YOUR_RESPONSE_TYPE}
+
+where:
+
+{YOUR\_APP\_ID} is the app ID.\
+{YOUR\_REDIRECT\_URL} is the application UUID or application name.\
+{YOUR\_STATE\_VALUE} is a unique string used to maintain application
+state between the request and callback.\
+{COMMA\_SEPARATED\_LIST\_OF\_PERMISSION\_NAMES} is a comma separated
+list of permission names which you would like the user to grant your
+application.\
+{YOUR\_RESPONSE\_TYPE}is the requested response type, either code or
+token. Defaults to code. Set the response type to token. With the
+response type set to token, the Dialog's response will include an OAuth
+user access token in the fragment of the URL the user is redirected to,
+as per the client-side authentication flow.
+
+Here is how itâs done in the Facebook login example:
+
+ var apiKey = $("#api-key").val();
+ var location = window.location.protocol + '//' + window.location.host;
+ var path = window.location.pathname;
+
+ var link = "https://www.facebook.com/dialog/oauth?client_id=";
+ link += apiKey;
+ link += "&redirect_uri=";
+ link += location+path
+ link += "&scope&COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES&response_type=token";
+
+ //now forward the user to facebook
+ window.location = link;
+
+Notice that the response type is set to token. As a result, a Facebook
+access token will be appended to the URL to which the user is
+redirected.
+
+### Step 3: Add the JavaScript SDK for Facebook
+
+Add the following Javascript SDK initialization code after the code that
+invokes the Facebook OAuth Dialog. The code will load and initialize the
+JavaScript SDK in your HTML page. Replace YOUR\_APP\_ID with the App ID
+noted in Step 1, and WWW.YOUR\_DOMAIN.COM with your own domain.
+
+ window.fbAsyncInit = function() {
+ FB.init({
+ appId : 'YOUR_APP_ID', // App ID
+ channelUrl : '//WWW.YOUR_DOMAIN.COM/channel.html', // Channel File
+ status : true, // check login status
+ cookie : true, // enable cookies to allow the server to access the session
+ xfbml : true // parse XFBML
+ });
+
+Here is how the window.fbAsynchInit() function is implemented in the
+Facebook login example:
+
+ //load up the facebook api sdk
+ window.fbAsyncInit = function() {
+ FB.init({
+ appId : '308790195893570', // App ID
+ channelUrl : '//usergridsdk.dev//examples/channel.html', // Channel File
+ status : true, // check login status
+ cookie : true, // enable cookies to allow the server to access the session
+ xfbml : true // parse XFBML
+ });
+ };
+
+### Step 4. Setup FB.login
+
+Whenever a user is either not logged into Facebook or not authorized for
+an app, it is useful to prompt them with the relevant dialog. The
+FB.login() Javascript SDK function automatically displays the correct
+one to the user.
+
+To integrate FB.login()Fwindow.fbAsyncInit() function in your existing
+code:
+
+ function login() {
+ FB.login(function(response) {
+ if (response.authResponse) {
+ // connected
+ } else {
+ // cancelled
+ }
+ });
+ }
+
+Here is how window.fbAsynchInit()FB.login() is implemented in the
+Facebook login example:
+
+ function login(facebookAccessToken) {
+ client.loginFacebook(facebookAccessToken, function(err, response){
+ var output = JSON.stringify(response, null, 2);
+ if (err) {
+ var html = '<pre>Oops! There was an error logging you in. \r\n\r\n';
+ html += 'Error: \r\n' + output+'</pre>';
+ } else {
+ var html = '<pre>Hurray! You have been logged in. \r\n\r\n';
+ html += 'Facebook Token: ' + '\r\n' + facebookAccessToken + '\r\n\r\n';
+ html += 'Facebook Profile data stored in Usergrid: \r\n' + output+'</pre>';
+ }
+ $('#facebook-status').html(html);
+ })
+ }
+
+The client.loginFacebook() function is provided by the Apache Usergrid
+JavaScript SDK. It uses the Facebook auth token to obtain an App
+Services auth token. If the Facebook access token is valid and the user
+does not already exist in Apache Usergrid, the function creates a user
+entity for the user. It also uses the Facebook access token to retrieve
+the user's profile information from Facebook.
+
+Here is what the client.loginFacebook() function looks like:
+
+ Usergrid.Client.prototype.loginFacebook = function (facebookToken, callback) {
+ var self = this;
+ var options = {
+ method:'GET',
+ endpoint:'auth/facebook',
+ qs:{
+ fb_access_token: facebookToken
+ }
+ };
+ this.request(options, function(err, data) {
+ var user = {};
+ if (err && self.logging) {
+ console.log('error trying to log user in');
+ } else {
+ user = new Usergrid.Entity('users', data.user);
+ self.setToken(data.access_token);
+ }
+ if (typeof(callback) === 'function') {
+ callback(err, data, user);
+ }
+ });
+ }
+
+Notice that the function also returns an Apache Usergrid access token,
+which you can use for subsequent Apache Usergrid API calls.
+
+Remember to create a client for your app, which is the main entry point
+to the JavaScript SDK for Apache Usergrid. You need to do this before you
+can use the SDK. Hereâs the code to create a client:
+
+ var client = new Usergrid.Client({
+ orgName:'yourorgname',
+ appName:'yourappname',
+ logging: true, //optional - turn on logging, off by default
+ buildCurl: true //optional - turn on curl commands, off by default
+ });
Added: incubator/usergrid/site/content/docs/features.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/features.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/features.md (added)
+++ incubator/usergrid/site/content/docs/features.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,198 @@
+---
+title: Apache Usergrid Features
+category: docs
+layout: docs
+---
+
+Apache Usergrid Features
+========================
+
+Apache Usergrid is a backend-as-a-service (BaaS) solution that enables you
+to quickly integrate valuable features into your app, including social
+graphs, user management, data storage, push notifications, performance
+monitoring, and more.
+
+Using Apache Usergrid, you can set up your own cloud-based data platform in
+minutes instead of months â no server-side coding or back-end
+development needed. This allows your team to focus on developing the
+rich features and user experience that truly differentiate your app,
+rather than the time-consuming details of implementing core back-end
+services and infrastructure.
+
+Data storage & management
+-------------------------
+
+### Application data
+
+At the core of Apache Usergrid is a flexible platform that can store any
+type of application data, from simple records like a catalog of books to
+complex associations like user relationships. No matter what type of
+data drives your app, you can store it in Apache Usergrid infrastructure as
+collections of data entities and immediately perform complex queries or
+full-text searches on any field. You can also create custom entities
+with custom properties, giving you the ability to store data and context
+in a way that makes sense for your app.
+
+To learn more about entities and collections, see [Apache Usergrid Data
+model](/app-services-data-model-1).
+
+For a complete list of default data entities available in Apache Usergrid,
+see [Default Data Entities](/default-data-entities).
+
+### Files & assets
+
+Images, video, and audio are key components of a great app experience.
+With Apache Usergrid, you can upload and retrieve binary objects from the
+same data store as the rest of your application data, eliminating the
+need to set up content delivery networks (CDNs) and easing
+implementation. We handle all the back-end details that keep your
+content quickly accessible.
+
+To learn more about files and asset storage, see [Uploading files and
+assets](/uploading-files-and-assets).
+
+### Flexible data querying
+
+One of Apache Usergrid' most powerful features is the ability to perform
+SQL-style queries and full-text searches on data entities, as well as
+their properties. This lets you quickly retrieve specific data entities
+based on multiple criteria, then utilize that data to power social
+features, target push notifications, perform user analysis, and more.
+
+Learn more about querying app data, see [Apache Usergrid data query
+overview](/app-services-data-query-overview).
+
+Social
+------
+
+### Entity relationships
+
+With Apache Usergrid you can create relationships between data entities to
+help build features, improve user experience, and contextualize data.
+For example, you might associate a user with their devices to capture
+valuable geolocation data, create relationships between users to build
+social graphs, or implement popular features such as activity streams.
+
+To learn more about entity relationships, see [Entity
+relationships](/entity-relationships).
+
+### Activity streams
+
+A key aspect of social networking apps is the ability to provide and
+publish data streams of user actions, such as ongoing lists of comments,
+activities, and tweets. Apache Usergrid simplifies management and routing
+of these data streams by providing an activity entity that is
+specifically designed to automatically create a relationship between
+activities and the user who created them.
+
+To learn more about activities and activity feeds, see
+[Activity](/activity).
+
+User management
+---------------
+
+### Registration and login
+
+Apache Usergrid makes it easy to add and manage users by providing the core
+services necessary to handle secure registration and log in, including
+OAuth 2.0-compliant client authentication. In addition, any number of
+default or custom data entities and properties can be associated with a
+user entity to create complete user profiles.
+
+To learn more about user management, see [User](/user).
+
+To learn more about authentication, see [Authenticating users and
+application clients](/authenticating-users-and-application-clients).
+
+### Roles & permissions
+
+Applications often require the ability to configure fine-grain control
+of user access to data, features and functionality. Apache Usergrid solves
+the implementation details of user access with roles and permissions.
+Simply create roles that represent user types or access levels, such as
+Administrator, then assign the necessary permissions to that role. With
+a single API call, you can then associate your roles with any user or
+group of users.
+
+To learn more about user roles and permissions, see [Managing access by
+defining permission rules](/managing-access-defining-permission-rules).
+
+### Groups
+
+Groups are a flexible way to organize your users based on any number of
+criteria. For example, you might group users based on interests or
+location to more effectively deliver relevant content, target offers, or
+customize campaigns. You can also take advantage of the groups entity to
+enable group-based social networking activities, such as allowing your
+users to create private information feeds or circles of friends.
+
+To learn more about groups, see [Group](/group).
+
+### Third-party authentication
+
+In addition to supporting user management and OAuth-based login for your
+app, Apache Usergrid also makes it easy to integrate third-party
+authentication through such popular services as Facebook, Twitter and
+other OAuth-enabled accounts. Providing third-party sign-in can improve
+user experience, while increasing adoption, giving you access to
+valuable information from social networks and services.
+
+To learn more about using third-party sign-in, see [Facebook sign
+in](/facebook-sign).
+
+Geolocation
+-----------
+
+The Apache Usergrid device entity allows you to capture geolocation data
+from your users' GPS-enabled devices to more effectively target
+campaigns, push notifications, offers and more. Geolocation also gives
+you an important data point for contextualizing and analyzing trends and
+user behavior.
+
+To learn more about geolocation, see [Geolocation](/geolocation).
+
+Push notifications
+------------------
+
+Push notifications are the most effective way to engage your users with
+relevant content, and thanks to Apache Usergrid, implementing them can be
+done in minutes. Simply register your app and your user's devices with a
+notification provider, such as Apple Push Notification Service or Google
+Cloud Messaging, then use the Apache Usergrid notification entity to send
+millions of push notifications a month at no cost. When used in
+conjunction with queries of user and application data, push
+notifications become a powerful tool for leveraging user data, ensuring
+relevancy and driving engagement.
+
+To learn more about push notifications, see [Push notifications
+overview](/push-notifications-overview).
+
+Configuration management
+------------------------
+
+By giving you the ability to push configuration changes directly to
+users' devices, Apache Usergrid lets you test and deliver bug fixes and
+performance improvements in real time. Remote configuration management
+can even be used to push changes to a subset of all users, enabling A/B
+testing of fixes, so that you can monitor and collect data to ensure
+your updates perform as intended before they are pushed to your entire
+user base.
+
+To learn more about configuration management, see [Configure your
+app](/configure-your-app).
+
+Error & performance monitoring
+------------------------------
+
+One of the largest barriers to the success of an app can be the ability
+of developers to respond quickly and precisely to performance issues and
+bugs. Apache Usergrid includes data logging and visualization tools that
+let you monitor and analyze network performance, usage patterns, crash
+statistics and other key metrics, giving you the data necessary to
+quickly manage performance issues as they arise.
+
+To learn more about usage monitoring, see [Monitor your appâs
+use](/monitor-your-app%E2%80%99s-use)
+
+To learn more about error monitoring, see [Get alerted to crashes and
+critical errors](/get-alerted-crashes-and-critical-errors)
Added: incubator/usergrid/site/content/docs/folder.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/folder.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/folder.md (added)
+++ incubator/usergrid/site/content/docs/folder.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,45 @@
+---
+title: Folder
+category: docs
+layout: docs
+---
+
+Folder
+======
+
+Folder entities are used primarily to organize content into a structure.
+For example, you can create a folders collection for media content, and
+within it have a âmusicâ folder for music content, and a âvideoâ folder
+for video content.
+
+Using Apache Usergrid APIs you can create, retrieve, update, delete, and
+query folder entities. See You do not have access to view this node for
+descriptions of these APIs.
+
+Folder properties
+-----------------
+
+The following are the system-defined properties for foldetr entities.
+You can create application-specific properties for a folder entity in
+addition to the system-defined properties. The system-defined properties
+are reserved. You cannot use these names to create other properties for
+a folder entity. In addition the folders name is reserved for the
+folders collection â you can't use it to name another collection.
+
+ Property Type Description
+ ---------- -------- ---------------------------------------------------------------------------------
+ uuid UUID the folderâs unique entity ID
+ type string "folder"
+ name string Folder name (mandatory)
+ created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+ modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+ owner UUID UUID of the folderâs owner (mandatory)
+ path string Relative path to the folder (mandatory)
+
+Folders have the following set properties.
+
+ Set Type Description
+ ------------- -------- -----------------------------------
+ connections string set of connections for the folder
+
+Â
Added: incubator/usergrid/site/content/docs/geolocation.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/geolocation.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/geolocation.md (added)
+++ incubator/usergrid/site/content/docs/geolocation.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,87 @@
+---
+title: Geolocation
+category: docs
+layout: docs
+---
+
+Geolocation
+===========
+
+Many of today's apps are enhanced by the use of *geolocation*, wireless
+detection of the physical location of a remote device. These apps are
+said to be *geolocation-aware* in that they query the device to
+determine the user's position and then use this data to further enhance
+the user's experience. For example, apps can capture the exact location
+where a picture was taken or a message was created.
+
+App services support geolocation on any entity, both built in (e.g.,
+users, groups) and user defined.
+
+Adding a location to an entity
+------------------------------
+
+To add a location to any entity, include the following member to the
+JSON in a POST or PUT call:
+
+ "location": {
+ "latitude": 37.779632,
+ "longitude": -122.395131
+ }
+
+For example, to store a listing of restaurants and their locations,
+start by creating a collection called restaurants:
+
+ POST https://api.usergrid.com/org_name/app_name/restaurants
+
+Next, add a new entity to the collection:
+
+ POST https://api.usergrid.com/org_name/app_name/restaurants
+ {
+ "name": "Rockadero",
+ "address": "21 Slate Street, Bedrock, CA",
+ "location": {
+ "latitude": 37.779632,
+ "longitude": -122.395131
+ }
+ }
+
+This creates a new restaurant entity called "Rockadero" with the
+longitude and latitude included as part of the object.
+
+You can also use geolocation to keep track of the location of a user. In
+this case, the user already exists, so you just need to update that user
+entity. Use POST and include the location member:
+
+ POST https://api.usergrid.com/org_name/app_name/users/fred
+ {
+ "location": {
+ "latitude": 37.779632,
+ "longitude": -122.395131
+ }
+ }
+
+This either adds or updates the location member of the user object for
+the user fred.
+
+Making queries against an entity's location
+-------------------------------------------
+
+When a location is added to an entity, it is easy to make queries
+against that data. For example, to see all restaurants within a 10 mile
+radius of the user's location, make a GET call against that entity, and
+include a search query in the following format:
+
+ location within <distance in meters> of <latitude>, <longitude>
+
+If we use the location of our user Fred, we first need to convert miles
+to meters. 1 mile is equivalent to 1609.344 meters, so 10 miles is about
+16093 meters. Thus, the API call looks like this:
+
+ GET https://api.usergrid.com/org_name/app_name/restaurants?ql=location within 16093 of 37.776753, -122.407846
+
+The url-encoded version looks like this:
+
+ https://api.usergrid.com/org_name/app_name/restaurants?ql=location%20within%2016093%20of%2037.776753%2C%20-122.407846&_=1337570474469
+
+In this case, the API call returns one entry for the Rockadero, which is
+exactly where Fred happens to be. Bon Appetit!