Return-Path: X-Original-To: apmail-usergrid-commits-archive@minotaur.apache.org Delivered-To: apmail-usergrid-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 253B410A15 for ; Mon, 18 Nov 2013 18:52:27 +0000 (UTC) Received: (qmail 37611 invoked by uid 500); 18 Nov 2013 18:52:27 -0000 Delivered-To: apmail-usergrid-commits-archive@usergrid.apache.org Received: (qmail 37593 invoked by uid 500); 18 Nov 2013 18:52:27 -0000 Mailing-List: contact commits-help@usergrid.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@usergrid.incubator.apache.org Delivered-To: mailing list commits@usergrid.incubator.apache.org Received: (qmail 37582 invoked by uid 99); 18 Nov 2013 18:52:27 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 18 Nov 2013 18:52:27 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,NORMAL_HTTP_TO_IP X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 18 Nov 2013 18:52:23 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 02DF62388C65; Mon, 18 Nov 2013 18:51:32 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1543106 [12/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/ ... Date: Mon, 18 Nov 2013 18:51:22 -0000 To: commits@usergrid.incubator.apache.org From: timanglade@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20131118185132.02DF62388C65@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: incubator/usergrid/site/content/docs/rest-endpoints.md URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/rest-endpoints.md?rev=1543106&view=auto ============================================================================== --- incubator/usergrid/site/content/docs/rest-endpoints.md (added) +++ incubator/usergrid/site/content/docs/rest-endpoints.md Mon Nov 18 18:51:18 2013 @@ -0,0 +1,918 @@ +--- +title: REST Endpoints +category: docs +layout: docs +--- + +REST Endpoints +============== + +### Base URL: https://api.usergrid.com/management + +  + +### Access Token + +URI + +Verb + +Content Types + +Action + +  + +/token +'{"grant\_type":"client\_credentials","client\_id":"{client\_id}","client\_secret":"client\_secret"}' + +POST + +application/json + +Obtain an access token (access type = organization) + +[Detail](/access-token) + +/token +'{"grant\_type":"password","username":"{username}":"password"="{password}"}' + +POST + +application/json + +Obtain an access token (access type = admin user) + +[Detail](/access-token) + +/{org\_id}/{app\_id}/token +'{"grant\_type":"client\_credentials","client\_id":"{client\_id}","client\_secret":"{client\_secret}"}' + +POST + +application/json + +Obtain an access token (access type = application) + +[Detail](/access-token) + +{org\_id}/{app\_id}/token +'{"grant\_type":"password","username":"{username}","password":"{password}"}' + +POST + +application/json + +Obtain an access token (access type = application user) + +[Detail](/access-token) + +### Admin users + +URI + +Verb + +Content Types + +Action + +  + +/users + +POST + +application/json + +Create an admin user + +[Detail](/docs/usergrid/content/admin-user#creating-an-admin-user) + +/users/{user|username|email|uuid} + +PUT + +application/json + +Update an admin user + +[Detail](/docs/usergrid/content/admin-user#updating-an-admin-user) + +/users/{user|username|email|uuid} + +GET + +application/json + +Get an admin user + +[Detail](/docs/usergrid/content/admin-user#getting-an-admin-user) + +/users/{user|username|email|uuid}/\ + password + +PUT + +application/json + +Set an admin user's password + +[Detail](/docs/usergrid/content/admin-user#setting-an-admin-user-s-password) + +users/resetpw + +GET + +application/json + +Initiate the reset of an admin user's password + +[Detail](/docs/usergrid/content/admin-user#setting-an-admin-user-s-password) + +/users/resetpw + +POST + +application/json + +Complete the reset of an admin user's password + +[Detail](/docs/usergrid/content/admin-user#setting-an-admin-user-s-password) + +/users/{user|username|email|uuid}/activate?\ + token={token}&confirm={confirm\_email} + +GET + +application/json + +Activate an admin user + +[Detail](/docs/usergrid/content/admin-user#activating-an-admin-user) + +/users/{user|username|email|uuid}/reactivate + +GET + +application/json + +Reactivate an admin user + +[Detail](/docs/usergrid/content/admin-user#reactivating-an-admin-user) + +/users/{user|username|email|uuid}/feed + +GET + +application/json + +Get an admin user's feed + +[Detail](/docs/usergrid/content/admin-user#getting-an-admin-user-s-activity-feed) + +### Applications + + ------------------- + See Organizations + ------------------- + +### Client authorization + +URI + +Verb + +Content Types + +Action + +  + +/authorize?response\_type={response\_type}&\ + client\_id={client\_id} + +GET + +application/json + +Authorize a client + +[Detail](/docs/usergrid/content/client-authorization) + +### Organizations + +URI + +Verb + +Content Types + +Action + +  + +/organizations|orgs + +POST + +application/json + +Create an organization + +[Detail](/docs/usergrid/content/organization#creating-an-organization) + +/organizations|orgs/{org\_name}|{uuid} + +GET + +application/json + +Retrieve an organization + +[Detail](/docs/usergrid/content/organization#getting-an-organization) + +/organizations|orgs/{org\_name}|{uuid}/\ + activate?token={token}&confirm={confirm\_email} + +GET + +application/json + +Activate an organization + +[Detail](/docs/usergrid/content/organization#activating-an-organization) + +/organizations|orgs/{org\_name}|{uuid}/\ + reactivate + +GET + +application/json + +Reactivate an organization + +[Detail](/docs/usergrid/content/organization#reactivating-an-organization) + +/organizations|orgs/{org\_name}|{uuid}/\ + credentials + +POST + +application/json + +Generate organization client credentials + +[Detail](/docs/usergrid/content/organization#generating-organization-client-credentials) + +/organizations|orgs/{org\_name}|{uuid}/\ + credentials + +GET + +application/json + +Retrieve organization client credentials + +[Detail](/docs/usergrid/content/organization#retrieving-organization-client-credentials) + +/organizations|orgs/{org\_name}|{uuid}/\ + feed + +GET + +application/json + +Retrieve an organization's activity feed + +[Detail](/docs/usergrid/content/organization#getting-an-organization-s-activity-feed) + +/organizations|orgs/{org\_name}|{org\_uuid}/\ + apps + +POST + +application/json + +Create an organization application + +[Detail](/docs/usergrid/content/organization#creating-an-organization-application) + +/organizations|orgs/{org\_name}|{org\_uuid}/\ + apps/{app\_name}|{app\_uuid} + +DELETE + +application/json + +Delete an organization application + +[Detail](/docs/usergrid/content/organization#deleting-an-organization-application) + +/organizations|orgs/{org\_name}|{uuid}/\ + applications|apps/{app\_name}|{uuid}/\ + credentials + +POST + +application/json + +Generate credentials for an organization application + +[Detail](/docs/usergrid/content/organization#generating-an-application-credentials) + +/organizations|orgs/{org\_name}|{uuid}/\ + applications|apps/\ + {app\_name}|{uuid}/credentials + +GET + +application/json + +Get credentials for an organization application + +[Detail](/docs/usergrid/content/organization#getting-application-credentials) + +/organizations|orgs/{org\_name}|{uuid}/\ + applications|apps + +GET + +application/json + +Get the applications in an organization + +[Detail](/docs/usergrid/content/organization#getting-the-applications-in-an-organization) + +/organizations|orgs/{org\_name}|{org\_uuid}/\ + users/{username|email|uuid} + +PUT + +application/json + +Adding an admin user to an organization + +[Detail](/docs/usergrid/content/organization#adding-an-admin-user-to-an-organization) + +/organizations|orgs/{org\_name}|{org\_uuid}/ users + +GET + +application/json + +Getting the admin users in an organization + +[Detail](/docs/usergrid/content/organization#getting-the-admin-users-in-an-organization) + +/organizations|orgs/{org\_name}|{org\_uuid}/\ + users/{username|email|uuid} + +DELETE + +application/json + +Removing an admin user from an organization + +[Detail](/docs/usergrid/content/organization#removing-an-admin-user-from-an-organization) + +### Base URL: https://api.usergrid.com + +### Activities + +URI + +Verb + +Content Types + +Action + +  + +/{org\_id}/{app\_id}/users/\ + {uuid|username}/activities + +POST + +application/json + +Create an activity + +[Detail](/docs/usergrid/content/activity#creating-an-activity) + +/{org\_id}/{app\_id}/groups/\ + {uuid|groupname}/activities + +POST + +application/json + +Post an activity to a group + +[Detail](/docs/usergrid/content/activity#posting-an-activity-to-a-group) + +### Assets + + ------------------------------------------------------- + See Collections (other than users, groups, and roles) + ------------------------------------------------------- + +### Collections (other than users, groups, and roles) + +URI + +Verb + +Content Types + +Action + +  + +/{org\_id}/{app\_id}/ + +GET + +application/json + +Retrieve all collections + +[Detail](/docs/usergrid/content/general-purpose-endpoints#create_entity) + +/{org\_id}/{app\_id}/{collection} + +POST + +application/json + +Create a new entity or collection + +[Detail](/docs/usergrid/content/general-purpose-endpoints#create_entity) + +/{org\_id}/{app\_id}/{collection}/\ + {uuid|name} + +GET + +application/json + +Retrieve an entity + +[Detail](/docs/usergrid/content/general-purpose-endpoints#get_entity_uuid) + +/{org\_id}/{app\_id}/{collection}/\ + {uuid|name} + +PUT + +application/json + +Update an entity + +[Detail](/docs/usergrid/content/general-purpose-endpoints#update_entity) + +/{org\_id}/{app\_id}/{collection}/\ + {uuid|name} + +DELETE + +application/json + +Delete an entity + +[Detail](/docs/usergrid/content/general-purpose-endpoints#delete_uuid) + +/{org\_id}/{app\_id}/{collection}?{query} + +GET + +application/json + +Query a collection + +[Detail](/docs/usergrid/content/general-purpose-endpoints#query_entity_collection) + +/{org\_id}/{app\_id}/{collection}?{query} + +PUT + +application/json + +Update a collection by query + +[Detail](/docs/usergrid/content/general-purpose-endpoints#update_collection) + +/{org\_id}/{app\_id}/{collection}/{entity\_id}/\ + {relationship}?{query} + +GET + +application/json + +Query an entity's collections or connections + +[Detail](/docs/usergrid/content/general-purpose-endpoints#query_entity_collection) + +/{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_id}\ + or\ + /{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_type}/{second\_entity\_id} + +POST + +application/json + +Add an entity to a collection or create a connection + +[Detail](/docs/usergrid/content/general-purpose-endpoints#put_entity) + +/{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_id}\ + or\ + /{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_type}/{second\_entity\_id} + +DELETE + +application/json + +Remove an entity from a collection or delete a connection + +[Detail](/docs/usergrid/content/general-purpose-endpoints#remove_entity) + +### Devices + + ------------------------------------------------------- + See Collections (other than users, groups, and roles) + ------------------------------------------------------- + +### Events + +URI + +Verb + +Content Types + +Action + +  + +/{org\_id}/{app\_id}/events + +POST + +application/json + +Create an event + +[Detail](/docs/usergrid/content/events-and-counters#new_event) + +### Folders + + ------------------------------------------------------- + See Collections (other than users, groups, and roles) + ------------------------------------------------------- + +### Groups + +URI + +Verb + +Content Types + +Action + +  + +/{org\_id}/{app\_id}/groups + +POST + +application/json + +Create a new group + +[Detail](/docs/usergrid/content/group#create_group) + +/{org\_id}/{app\_id}/groups/\ + {uuid|groupname}/users/{uuid|username} + +POST + +application/json + +Add a user to a group + +[Detail](/docs/usergrid/content/group#add_user_group) + +/{org\_id}/{app\_id}/groups/\ + {uuid|groupname} + +GET + +application/json + +Get a group + +[Detail](/docs/usergrid/content/group#get_group) + +/{org\_id}{app\_id}/groups/\ + {uuid|groupname} + +PUT + +application/json + +Update a group + +[Detail](/docs/usergrid/content/group#update_group) + +/{org\_id}/{app\_id}/groups/\ + {uuid|groupname}/users/{uuid|username} + +DELETE + +application/json + +Delete user from a group + +[Detail](/docs/usergrid/content/group#delete_user_group) + +/{org\_id}/{app\_id}/groups/\ + {uuid|groupname}/feed + +GET + +application/json + +Get a group's feed + +[Detail](/docs/usergrid/content/group#getting-a-group-s-feed) + +### Roles + +URI + +Verb + +Content Types + +Action + +  + +/{org\_id}/{app\_id}/roles + +POST + +application/json + +Create a new role + +[Detail](/docs/usergrid/content/role#create_role) + +/{org\_id}/{app\_id}/roles + +GET + +application/json + +Get the roles in an application + +[Detail](/docs/usergrid/content/role#get_roles) + +/{org\_id}/{app\_id}/roles/{rolename} + +DELETE + +application/json + +Delete a role + +[Detail](/docs/usergrid/content/role#delete_role) + +/{org\_id}/{app\_id}/roles/\ + {rolename|role\_id}/permissions + +GET + +application/json + +Get permissions for a role + +[Detail](/docs/usergrid/content/role#get_permission) + +/{org\_id}/{app\_id}/roles/\ + {rolename|role\_id}/permissions + +POST + +application/json + +Add permissions to a role + +[Detail](/docs/usergrid/content/role#add_permission) + +{org\_id}/{app\_id}/roles/\ + {rolename|role\_id}/permissions?\ + permission={grant\_url\_pattern} + +DELETE + +application/json + +Delete permissions from a role + +[Detail](/docs/usergrid/content/role#delete_permission) + +/{org\_id}/{app\_id}/roles/{role\_id}/\ + users/{uuid|username}\ + or\ + /{org\_id}/{app\_id}/users/\ + {uuid|username}/roles/{role\_id} + +POST + +application/json + +Add a user to a role + +[Detail](/docs/usergrid/content/role#adding-a-user-to-a-role) + +/{org\_id}/{app\_id}/roles/{role\_id}/\ + users + +GET + +application/json + +Get the users in a role + +[Detail](/docs/usergrid/content/role#getting-the-users-in-a-role) + +/{org\_id}/{app\_id}/roles/{role\_id}/\ + users/{uuid|username} + +DELETE + +application/json + +Delete a user from a role + +[Detail](/docs/usergrid/content/role#deleting-a-user-from-a-role) + +### Users + +URI + +Verb + +Content Types + +Action + +  + +/{org\_id}/{app\_id}/users + +POST + +application/json + +Create a user in the users collection + +[Detail](/docs/usergrid/content/user#create_user) + +/{org\_id}/{app\_id}/users/{user}/\ + password + +POST + +application/json + +Set a user's password or reset the user's existing password + +[Detail](/docs/usergrid/content/user#set_password) + +/{org\_id}/{app\_id}/users/\ + {uuid|username|email\_address} + +GET + +application/json + +Retrieve a user + +[Detail](/docs/usergrid/content/user#uuid) + +/{org\_id}/{app\_id}/users/\ + {uuid|username} + +PUT + +application/json + +Update a user + +[Detail](/docs/usergrid/content/user#update_user) + +/{org\_id}/{app\_id}/users/{uuid|username} + +DELETE + +application/json + +Delete a user + +[Detail](/docs/usergrid/content/user#delete_user) + +/{org\_id}/{app\_id}/users?{query} + +GET + +application/json + +Query to get users + +[Detail](/docs/usergrid/content/user#query_get) + +/{org\_id}/{app\_id}/groups/\ + {uuid|groupname}/users/{uuid|username} + +POST + +application/json + +Add a user to a group + +[Detail](/docs/usergrid/content/user#add_user_group) + +/{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_id}\ + or\ + /{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_type}/{second\_entity\_id} + +POST + +application/json + +Add a user to a collection or create a connection + +[Detail](/docs/usergrid/content/user#add_collection) + +/{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_id}\ + or\ + /{org\_id}/{app\_id}/{collection}/\ + {first\_entity\_id}/{relationship}/\ + {second\_entity\_type}/{second\_entity\_id} + +DELETE + +application/json + +Remove a user from a collection or delete a connection + +[Detail](/docs/usergrid/content/user#delete_collection) + +/{org\_id}/{app\_id}/users/{uuid|username}/\ + {relationship}?{query} + +GET + +application/json + +Query a user's collections or connections + +[Detail](/docs/usergrid/content/user#query_collection) + +/{org\_id}/{app\_id}/users/\ + {uuid|username}/feed + +GET + +application/json + +Get a user's feed + +[Detail](/docs/usergrid/content/user#getting-a-user-s-feed) + +### Notifications, Notifiers, and Receipts + + ------------------------------------------------------------------- + See [Create & Manage Notifications](/create-manage-notifications) + ------------------------------------------------------------------- + +  Added: incubator/usergrid/site/content/docs/retrieving-collections.md URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/retrieving-collections.md?rev=1543106&view=auto ============================================================================== --- incubator/usergrid/site/content/docs/retrieving-collections.md (added) +++ incubator/usergrid/site/content/docs/retrieving-collections.md Mon Nov 18 18:51:18 2013 @@ -0,0 +1,484 @@ +--- +title: Retrieving Collections +category: docs +layout: docs +--- + +Retrieving Collections +====================== + +This article describes how to retrieve all of the entities in a +collection. + +By default, the Apache Usergrid API returns 10 entities per request. For +collections with more than 10 entities, use the returned 'cursor' +property to retrieve the next 10 entities in the result set. You may +also use the `LIMIT` parameter in a query string to increase the number +of results returned. For more information on using cursors, see +[Managing large sets of results](/working-queries#cursor). + +**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. + +Retrieving sets of entities from a collection +--------------------------------------------- + +- [cURL](#curl_get_collection) +- [iOS](#ios_get_collection) +- [Android](#android_get_collection) +- [JavaScript (HTML5)](#javascript_get_collection) +- [Ruby](#ruby_get_collection) +- [Node.js](#nodejs_get_collection) + +### Example Request/Response + +#### Request: + + curl -X GET "https://api.usergrid.com/your-org/your-app/items" + +#### Response: + + { + "action" : "get", + "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" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378426821261, + "duration" : 35, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### Request Syntax + + curl -X GET https://api.usergrid.com/// + +### 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*)getCollection { + + //specify the entity type that corresponds to the collection to be retrieved + NSString *type = @"item"; + + //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]; + + ApigeeCollection *collection = [[ApigeeCollection alloc] init:apigeeClient.dataClient type:type]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + + } + + + +#### Response: + + { + "action" : "get", + "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" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378426821261, + "duration" : 35, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### SDK Method + + (ApigeeCollection*)getCollection:(NSString*)type + +### Properties + + Parameter Description + ----------- ---------------------------------------------------------------- + type The entity type associated with the collection to be retrieved + +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 + Map queryString = null; //we don't need any additional query parameters, in this case + + //call getCollectionAsync to initiate the asynchronous API call + dataClient.getCollectionAsync(type, queryString, new ApiResponseCallback() { + + //If getEntitiesAsync fails, catch the error + @Override + public void onException(Exception e) { + // Error + } + + //If getCollectionAsync 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":"get","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":1378505935248,"availability":"in-stock","metadata":{"path":"/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"}},{"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":"1a9356ba-1682-11e3-a72a-81581bbaf055","price":"2.50","created":1378423379867,"name":"bread","modified":1378423379867,"metadata":{"path":"/items/1a9356ba-1682-11e3-a72a-81581bbaf055"}}],"params":{},"path":"/items","rawResponse":"{ + "action" : "get", + "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" : 1378505935248, + "availability" : "in-stock", + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "4.00" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378512710357, + "duration" : 39, + "organization" : "your-org", + "applicationName" : "your-app" + } + ","uri":"http://api.usergrid.com/your-org/your-app/items","timestamp":1378512710357,"entityCount":2,"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":1378505935248,"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":"1a9356ba-1682-11e3-a72a-81581bbaf055","price":"2.50","created":1378423379867,"name":"bread","modified":1378423379867,"metadata":{"path":"/items/1a9356ba-1682-11e3-a72a-81581bbaf055"}},"organi zation":"your-org","duration":39,"applicationName":"your-app"} + + +### SDK Method + +Asynchronous: + + getCollectionAsync(String type, Map queryString, ApiResponseCallback callback) + +Synchronous: + + ApiResponse getCollection(String type, Map queryString) + +### Properties + + Parameter Description + ------------- ---------------------------------------------------------------------------------- + type The entity type being retrieved + queryString Map object of entity properties to be matched for the collection to be retrieved + callback Callback function (Asynchronous calls only) + +This example uses the [Apache Usergrid JavaScript (HTML5) +SDK](/app-services-sdks#javascript). + +### Example Request/Response + +#### Request: + + var dataClient = new Usergrid.Client({ + orgName:'your-org', + appName:'your-app' + }); + + var options = { + type:"item", //Required - the type of collection to be retrieved + client:dataClient //Required + }; + + //Create a collection object to hold the response + var collection = new Usergrid.Collection(options); + + //Call request to initiate the API call + collection.fetch( + function() { + //success callback + }, + function() { + //error callback + } + ); + + +#### Response: + + Object {action: "get", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"…} + action: "get" + application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0" + applicationName: "your-app" + count: 2 + duration: 33 + entities: Array[2] + 0: Object + created: 1378423379867 + metadata: Object + modified: 1378423379867 + name: "bread" + price: "2.50" + type: "item" + uuid: "1a9356ba-1682-11e3-a72a-81581bbaf055" + __proto__: Object + 1: Object + created: 1378405020796 + metadata: Object + modified: 1378405020796 + name: "milk" + price: "3.25" + type: "item" + uuid: "5bb76bca-1657-11e3-903f-9ff6c621a7a4" + __proto__: Object + length: 2 + __proto__: Array[0] + organization: "your-org" + params: Object + path: "/items" + timestamp: 1378427598013 + uri: "http://api.usergrid.com/your-org/your-app/items" + __proto__: Object + + +### SDK Method + + Collection.fetch(callback); + +### Parameters + + Parameter Description + ----------- ---------------------------------------------- + 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' + + dataClient = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}" + + begin + # Retrieve the collection by referencing the [type] + # and save the response + response = dataClient['items'].entity + + rescue + #fail + end + + + +#### Response: + + { + "action" : "get", + "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" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378426821261, + "duration" : 35, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### SDK Method + + Application.[].entity + +### Parameters + + Parameter Description + -------------- ---------------------------------------------------------------- + entity\_type The entity type associated with the collection to be retrieved + +This example uses the [Apache Usergrid Node.js +module](/app-services-sdks#nodejs). + +### Example Request/Response + +#### Request: + + var dataClient = new Usergrid.client({ + orgName:'your-org', + appName:'your-app' + }); + + var options = { + type:"item", //Required - the type of collection to be retrieved + client:dataClient //Required + }; + + //Create a collection object to hold the response + var collection = new Usergrid.collection(options); + + //Call request to initiate the API call + collection.fetch(function (error, response) { + if (error) { + //error + } else { + //success + } + }); + + +#### Response: + + { action: 'get', + 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: 1378405020796, + metadata: [Object], + price: '3.25' }, + { uuid: '1a9356ba-1682-11e3-a72a-81581bbaf055', + type: 'item', + name: 'bread', + created: 1378423379867, + modified: 1378423379867, + metadata: [Object], + price: '2.50' } ], + timestamp: 1378428161834, + duration: 33, + organization: 'your-org', + applicationName: 'your-app' } + + +### SDK Method + + Collection.fetch(callback) + +### Parameters + + Parameter Description + ----------- ---------------------------------------------- + callback Callback function to handle the API response + +  Added: incubator/usergrid/site/content/docs/retrieving-data-entities.md URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/retrieving-data-entities.md?rev=1543106&view=auto ============================================================================== --- incubator/usergrid/site/content/docs/retrieving-data-entities.md (added) +++ incubator/usergrid/site/content/docs/retrieving-data-entities.md Mon Nov 18 18:51:18 2013 @@ -0,0 +1,1092 @@ +--- +title: Retrieving Data Entities +category: docs +layout: docs +--- + +Retrieving Data Entities +======================== + +This article describes how to retrieve entities from 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. + +With the exception of the `user` entity, all data entities can be +retrieved by using their UUID or a 'name' property. The `user` entity +can be retrieved by UUID or the 'username' property. The value for the +'name' or 'username' property must be unique. + +Retrieving an entity +-------------------- + +- [cURL](#curl_get_entity) +- [iOS](#ios_get_entity) +- [Android](#android_get_entity) +- [JavaScript (HTML5)](#javascript_get_entity) +- [Ruby](#ruby_get_entity) +- [Node.js](#nodejs_get_entity) + +### Example Request/Response + +#### Request: + +Retrieve by UUID: + + curl -X GET "https://api.usergrid.com/your-org/your-app/items/da4a50dc-38dc-11e2-b2e4-02e81adcf3d0" + +Retrieve by 'name' property: + + curl -X GET "https://api.usergrid.com/your-org/your-app/items/milk" + +#### Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/amuramoto/sandbox/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + } ], + "timestamp" : 1378405025763, + "duration" : 31, + "organization" : "amuramoto", + "applicationName" : "sandbox" + } + +### Request Syntax + + curl -X GET https://api.usergrid.com//// + +### 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*)getEntity { + + //specify the entity collection and UUID or name to be retrieved + NSString *endpoint = @"items/b3aad0a4-f322-11e2-a9c1-999e12039f87"; + + NSString *query = 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 getEntities:endpoint query:query]; + + @try { + //success + } + + @catch (NSException * e) { + //fail + } + + } + + +#### Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/amuramoto/sandbox/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + } ], + "timestamp" : 1378405025763, + "duration" : 31, + "organization" : "amuramoto", + "applicationName" : "sandbox" + } + +### SDK Method + + (ApigeeClientResponse *)getEntities: (NSString *)endpoint query:(NSString *)query + +### Properties + ++--------------------------------------+--------------------------------------+ +| Parameter | Description | ++======================================+======================================+ +| endpoint | The collection and entity identifier | +| | of the entity to be retrieved in the | +| | following format: | +| | | +| | / | ++--------------------------------------+--------------------------------------+ +| query | An optional query string. Requests | +| | for a specific entity should set the | +| | value to `nil` | ++--------------------------------------+--------------------------------------+ + +\ + +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 query = "uuid = b3aad0a4-f322-11e2-a9c1-999e12039f87; + + //call getEntitiesAsync to initiate the asynchronous API call + dataClient.getEntitiesAsync(type, query, new ApiResponseCallback() { + + //If getEntitiesAsync fails, catch the error + @Override + public void onException(Exception e) { + // Error + } + + //If createEntityAsync 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":"post", + "application":"f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "entities":[{ + "Client":{ + "accessToken":null, + "apiUrl":"http://api.usergrid.com", + "applicationId":"your-app", + "clientId":null, + "clientSecret":null, + "currentOrganization":null, + "loggedInUser":null, + "organizationId":"your-org" + }, + "type":"item", + "uuid":"fd29157a-e980-11e2-afcc-652a12f1ce72", + "created":1373475098695, + "modified":1373475098695, + "metadata":{ + "path":"/items/fd29157a-e980-11e2-afcc-652a12f1ce72" + } + }], + + "params":{}, + "path":"/items", + "rawResponse":"{ + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items", + "entities" : [ { + "uuid" : "fd29157a-e980-11e2-afcc-652a12f1ce72", + "type" : "item", + "created" : 1373475098695, + "modified" : 1373475098695, + "metadata" : { + "path" : "/items/fd29157a-e980-11e2-afcc-652a12f1ce72" + } + } ], + "timestamp" : 1373475098689, + "duration" : 24, + "organization" : "your-org", + "applicationName" : "your-app" + }", + "uri":"http://api.usergrid.com/your-org/your-app/items", + "timestamp":1373475098689, + "entityCount":1, + "firstEntity":{ + "Client":{ + "accessToken":null, + "apiUrl":"http://api.usergrid.com", + "applicationId":"your-app", + "clientId":null, + "clientSecret":null, + "currentOrganization":null, + "loggedInUser":null, + "organizationId":"your-org" + }, + "type":"item", + "uuid":"fd29157a-e980-11e2-afcc-652a12f1ce72", + "created":1373475098695, + "modified":1373475098695, + "metadata":{ + "path":"/items/fd29157a-e980-11e2-afcc-652a12f1ce72" + } + }, + "lastEntity":{ + "Client":{ + "accessToken":null, + "apiUrl":"http://api.usergrid.com", + "applicationId":"your-app", + "clientId":null, + "clientSecret":null, + "currentOrganization":null, + "loggedInUser":null, + "organizationId":"your-org" + }, + "type":"item", + "uuid":"fd29157a-e980-11e2-afcc-652a12f1ce72", + "created":1373475098695, + "modified":1373475098695, + "metadata":{ + "path":"/items/fd29157a-e980-11e2-afcc-652a12f1ce72" + } + }, + "organization":"your-org", + "duration":24, + "applicationName":"your-app" + } + + +### SDK Method + +Asynchronous: + + getEntitiesAsync(String type, String queryString, ApiResponseCallback callback) + +Synchronous: + + ApiResponse getEntities(String type, String queryString) + +### Properties + ++--------------------------------------+--------------------------------------+ +| Parameter | Description | ++======================================+======================================+ +| type | The entity type being retrieved | ++--------------------------------------+--------------------------------------+ +| queryString | A query string that specifies the | +| | property of the entity to be | +| | retrieved in the following format: | +| | | +| | = | +| | | +| | To retrieve a specific entity, use | +| | the unique entity *uuid* or *name* | +| | property. | ++--------------------------------------+--------------------------------------+ +| callback | Callback function (Asynchronous | +| | calls only) | ++--------------------------------------+--------------------------------------+ + +This example uses the [Apache Usergrid JavaScript (HTML5) +SDK](/app-services-sdks#javascript). + +### Example Request/Response + +#### Request: + + var properties = { + 'type':'item', + 'name':'milk' //This method also supports retrieval by uuid + }; + + client.getEntity(properties, function (error, response) { + if (err) { + //error + } else { + //success + } + }); + + +#### Response: + + Usergrid.Entity {_client: Usergrid.Client, _data: Object, serialize: function, get: function, set: function…} + _client: Usergrid.Client + URI: "https://api.usergrid.com" + _callTimeout: 30000 + _callTimeoutCallback: null + _end: 1378413997721 + _start: 1378413997493 + appName: "your-app" + buildCurl: false + logging: true + logoutCallback: null + orgName: "your-org" + __proto__: Object + _data: Object + created: 1378405020796 + metadata: Object + modified: 1378405020796 + name: "milk" + price: "3.25" + type: "item" + uuid: "5bb76bca-1657-11e3-903f-9ff6c621a7a4" + __proto__: Object + __proto__: Object + + +### SDK Method + + getEntity(properties, callback) + +### Parameters + +#### getEntity(): + ++--------------------------------------+--------------------------------------+ +| Parameter | Description | ++======================================+======================================+ +| properties | Object that contains the following | +| | properties of the entity to be | +| | retrieved: | +| | | +| | - type: the entity type to be | +| | retrieved | +| | - name: the name of the entity to | +| | be retrieved | +| | - uuid: the uuid of the entity to | +| | be retrieved | +| | | +| | You only need to specify name or | +| | uuid, not both. | ++--------------------------------------+--------------------------------------+ +| callback | Callback function | ++--------------------------------------+--------------------------------------+ + +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 + # Retrieve the entity by referencing the [type] and [uuid or name] + # and save the response + response = client['items']['milk'].entity + + rescue + #fail + end + + +#### Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/items", + "uri" : "http://api.usergrid.com/amuramoto/sandbox/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + } ], + "timestamp" : 1378405025763, + "duration" : 31, + "organization" : "amuramoto", + "applicationName" : "sandbox" + } + +### SDK Method + + application[][].entity + +### Parameters + +Parameter + +Description + +entity\_type + +The entity type to be retrieved + +entity\_uuid|entity\_name + +The name or UUID of the entity to be retrieved + +This example uses the [Apache Usergrid Node.js +module](/app-services-sdks#nodejs). + +### Example Request/Response + +#### Request: + + var properties = { + method:'GET', + type:'items', + name:'da4a50dc-38dc-11e2-b2e4-02e81adcf3d0' + }; + + client.getEntity(properties, function (error, response) { + if (error) { + //error + } else { + //success + } + }); + + +#### Response: + + { _client: + { URI: 'https://api.usergrid.com', + orgName: 'your-org', + appName: 'your-app', + authType: 'NONE', + clientId: undefined, + clientSecret: undefined, + token: null, + buildCurl: false, + logging: true, + _callTimeout: 30000, + _callTimeoutCallback: null, + logoutCallback: null, + _start: 1378423148601, + _end: 1378423149028 }, + _data: + { method: 'GET', + type: 'item', + name: 'milk', + uuid: '5bb76bca-1657-11e3-903f-9ff6c621a7a4', + created: 1378405020796, + modified: 1378405020796, + metadata: { path: '/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4' }, + price: '3.25' } } + + +### SDK Method + + getEntity(properties, callback) + +### Parameters + +Parameter + +Description + +Object that contains the following properties of the entity to be +retrieved: + +- type: the entity type to be retrieved +- name: the name of the entity to be retrieved +- uuid: the uuid of the entity to be retrieved + +You only need to specify name or uuid, not both. + +callback + +Callback function + +Retrieving multiple entities +---------------------------- + +- [cURL](#curl_get_multentity) +- [iOS](#ios_get_multentity) +- [Android](#android_get_multentity) +- [JavaScript (HTML5)](#javascript_get_multentity) +- [Ruby](#ruby_get_multentity) +- [Node.js](#nodejs_get_multentity) + +This example describes how to retrieve multiple entities by UUID. You +can also retrieve a set of entities by using a query string. For more +information on querying your data, see [Basic query +syntax](/basic-query-syntax). + +### Example Request/Response + +#### Request: + + //note the url-encoded query string + curl -X GET "https://api.usergrid.com/your-org/your-app/items?ql=name%3D'milk'%20OR%20UUID%3D1a9356ba-1682-11e3-a72a-81581bbaf055&limit=" + + +**Note:** The query parameter of the request must be url encoded for +curl requests + +#### Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "name='milk' OR UUID=1a9356ba-1682-11e3-a72a-81581bbaf055" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378423793729, + "duration" : 63, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### Request Syntax + + curl -X GET https://api.usergrid.com///?ql= uuid = OR uuid = ; ... + +### Parameters + ++--------------------------------------+--------------------------------------+ +| Parameter | Description | ++======================================+======================================+ +| org\_id | Organization UUID or organization | +| | name | ++--------------------------------------+--------------------------------------+ +| app\_id | Application UUID or application name | ++--------------------------------------+--------------------------------------+ +| collection | Collection UUID or collection name | ++--------------------------------------+--------------------------------------+ +| query | A url-encoded query string of entity | +| | properties to be matched in the | +| | following format: | +| | | +| | ?ql=uuid=""" OR nam | +| | e="" OR... | +| | | +| | You may also specify the following | +| | for certain entity types: | +| | | +| | User entities: | +| | `username = ` | +| | | +| | All other entities except groups: | +| | `name = ` | ++--------------------------------------+--------------------------------------+ + +This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios). + +### Example Request/Response + +#### Request: + + -(NSString*)getEntity { + + //specify the entity type to be retrieved + NSString *type = @"item"; + + //specify the uuid of the entity to be retrieved in a query string + NSString *query = @"uuid = b3aad0a4-f322-11e2-a9c1-999e12039f87 or name = 'bread'"; + + //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 getEntities:type queryString:query]; + + @try { + //success + } + @catch (NSException * e) { + //fail + } + + } + + + +#### Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "name='milk' OR UUID=1a9356ba-1682-11e3-a72a-81581bbaf055" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378423793729, + "duration" : 63, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### SDK Method + + (ApigeeClientResponse *)getEntities: (NSString *)type queryString:(NSString *)queryString + +### Properties + ++--------------------------------------+--------------------------------------+ +| Parameter | Description | ++======================================+======================================+ +| type | The entity type being retrieved | ++--------------------------------------+--------------------------------------+ +| queryString | A query string of entity properties | +| | to be matched for the entities to be | +| | retrieved in the following format: | +| | = OR | +| | = OR ... | ++--------------------------------------+--------------------------------------+ + +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 query = "uuid = f8726dda-f54a-11e2-b560-575bef89aaed OR name = 'bread'"; //query string specifying the entities to be retrieved + + + //call getEntitiesAsync to initiate the asynchronous API call + dataClient.getEntitiesAsync(type, query, new ApiResponseCallback() { + + //If getEntitiesAsync fails, catch the error + @Override + public void onException(Exception e) { + // Error + } + + //If createEntityAsync 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":"get","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":"3.25","created":1378405020796,"name":"milk","modified":1378405020796,"metadata":{"path":"/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4"}},{"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":"1a9356ba-1682-11e3-a72a-81581bbaf055","price":"2.50","created":1378423379867,"name":"bread","modified":1378423379867,"metadata":{"path":"/items/1a9356ba-1682-11e3-a72a-81581bbaf055"}}],"params":{"ql":["uuid = 5bb76bca-1657-11e3-903f-9ff6c621a7a4 OR name = 'bread'"]}, "path":"/items","rawResponse":"{ + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "uuid = 5bb76bca-1657-11e3-903f-9ff6c621a7a4 OR name = 'bread'" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378425390343, + "duration" : 42, + "organization" : "your-org", + "applicationName" : "your-app" + } + ","uri":"http://api.usergrid.com/your-org/your-app/items","timestamp":1378425390343,"entityCount":2,"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":"3.25","created":1378405020796,"name":"milk","modified":1378405020796,"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":"1a9356ba-1682-11e3-a72a-81581bbaf055","price":"2.50","created":1378423379867,"name":"bread","modified":1378423379867,"metadata":{"path":"/items/1a9356ba-1682-11e3-a72a-81581bbaf055"}},"organization":"your-org","duration": 42,"applicationName":"your-app"} + + +### SDK Method + +Asynchronous: + + getEntitiesAsync(String type, String queryString, ApiResponseCallback callback) + +Synchronous: + + ApiResponse getEntities(String type, String queryString) + +### Properties + + Parameter Description + ------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------- + type The entity type being retrieved + queryString A query string of entity properties to be matched for the entities to be retrieved in the following format: \=\ OR \=\ OR ... + callback Callback function (Asynchronous calls only) + +This example uses the [Apache Usergrid JavaScript (HTML5) +module](/app-services-sdks#javascript). + +### Example Request/Response + +#### Request: + + var dataClient = new Usergrid.Client({ + orgName:'your-org', + appName:'your-app' + }); + + var options = { + endpoint:"items", + //Define the query - note the use of the 'ql' property + //Note the use of the single-quote for the string 'bread' + qs:{ql:"name='bread' or uuid=b3aad0a4-f322-11e2-a9c1-999e12039f87"} + }; + + //Call request to initiate the API call + dataClient.request(options, function (error, response) { + if (err) { + //error — GET failed + } else { + //success + } + }); + + +#### Response: + + Object {action: "get", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"…} + action: "get" + application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0" + applicationName: "your-app" + count: 2 + duration: 57 + entities: Array[2] + 0: Object + created: 1378423379867 + metadata: Object + modified: 1378423379867 + name: "bread" + price: "2.50" + type: "item" + uuid: "1a9356ba-1682-11e3-a72a-81581bbaf055" + __proto__: Object + 1: Object + created: 1378405020796 + metadata: Object + modified: 1378405020796 + name: "milk" + price: "3.25" + type: "item" + uuid: "5bb76bca-1657-11e3-903f-9ff6c621a7a4" + __proto__: Object + length: 2 + __proto__: Array[0] + organization: "your-org" + params: Object + path: "/items" + timestamp: 1378426195611 + uri: "http://api.usergrid.com/your-org/your-app/items" + __proto__: Object + + +### SDK Method + + request(properties,callback) + +### Parameters + + Parameter Description + ------------ -------------------------------------------- + properties Object that contains the entity properties + callback Callback function + +This example uses the [Apache Usergrid RubyGem](/app-services-sdks#ruby). + +### Example Request/Response + +#### Request: + +This example uses the [Apache Usergrid RubyGem](/app-services-sdks#ruby). + + #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 that contains them, and a query the specifies the name or uuid of the entities to retrieve + response = client['items'].query("uuid=a86e614a-efc8-11e2-94fb-a94a8e3669a7 or uuid=71c29a2a-efc9-11e2-a3cc-ed942506cf87").entity + + rescue + #fail + end + + +#### Response: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "ql" : [ "name='milk' OR UUID=1a9356ba-1682-11e3-a72a-81581bbaf055" ] + }, + "path" : "/items", + "uri" : "http://api.usergrid.com/your-org/your-app/items", + "entities" : [ { + "uuid" : "5bb76bca-1657-11e3-903f-9ff6c621a7a4", + "type" : "item", + "name" : "milk", + "created" : 1378405020796, + "modified" : 1378405020796, + "metadata" : { + "path" : "/items/5bb76bca-1657-11e3-903f-9ff6c621a7a4" + }, + "name" : "milk", + "price" : "3.25" + }, { + "uuid" : "1a9356ba-1682-11e3-a72a-81581bbaf055", + "type" : "item", + "name" : "bread", + "created" : 1378423379867, + "modified" : 1378423379867, + "metadata" : { + "path" : "/items/1a9356ba-1682-11e3-a72a-81581bbaf055" + }, + "name" : "bread", + "price" : "2.50" + } ], + "timestamp" : 1378423793729, + "duration" : 63, + "organization" : "your-org", + "applicationName" : "your-app", + "count" : 2 + } + +### SDK Method + + Application.[].query() + +### Parameters + ++--------------------------------------+--------------------------------------+ +| Parameter | Description | ++======================================+======================================+ +| collection | The name or uuid of the collection | +| | that contains the data entities to | +| | be retrieved | ++--------------------------------------+--------------------------------------+ +| query | A query string that specifies the | +| | property of the entity to be | +| | retrieved in the following format: | +| | = | +| | | +| | To retrieve a specific entity, use | +| | the unique entity *uuid* or *name* | +| | property. | ++--------------------------------------+--------------------------------------+ + +This example uses the [Apache Usergrid Node.js +module](/app-services-sdks#nodejs). + +### Example Request/Response + +#### Request: + + var dataClient = new Usergrid.client({ + orgName:'your-org', + appName:'your-app' + }); + + var options = { + endpoint:"items", + //Define the query - note the use of the 'ql' property + //Note the use of the single-quote for the string 'bread' + qs:{ql:"name='bread' or uuid=b3aad0a4-f322-11e2-a9c1-999e12039f87"} + }; + + //Call request to initiate the API call + dataClient.request(options, function (error, response) { + if (error) { + //error — GET failed + } else { + //success + } + }); + + +#### Response: + + { action: 'get', + application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0', + params: { ql: [ 'name=\'bread\' or uuid=5bb76bca-1657-11e3-903f-9ff6c621a7a4' ] }, + path: '/items', + uri: 'http://api.usergrid.com/your-org/your-app/items', + entities: + [ { uuid: '1a9356ba-1682-11e3-a72a-81581bbaf055', + type: 'item', + name: 'bread', + created: 1378423379867, + modified: 1378423379867, + metadata: [Object], + price: '2.50' }, + { uuid: '5bb76bca-1657-11e3-903f-9ff6c621a7a4', + type: 'item', + name: 'milk', + created: 1378405020796, + modified: 1378405020796, + metadata: [Object], + price: '3.25' } ], + timestamp: 1378426688958, + duration: 37, + organization: 'your-org', + applicationName: 'your-app', + count: 2 } + + +### SDK Method + + request(properties,callback) + +### Parameters + + Parameter Description + ------------ -------------------------------------------- + properties Object that contains the entity properties + callback Callback function + +Add new comment +--------------- + +Your name + +Email + +Provide your email address if you wish to be contacted offline about +your comment.\ +We will not display your email address as part of your comment. + +Comment \* + +We'd love your feedback and perspective! Please be as specific as +possible. + +Word verification \* + +![Type the characters you see in this +picture.](http://173.193.242.189:80/v1/captcha/131019a6363a732611.png) +([verify using audio](#)) + +Type the characters you see in the picture above; if you can't read +them, submit the form and a new image will be generated. Not case +sensitive.