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 [13/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/ ...
Added: incubator/usergrid/site/content/docs/role.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/role.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/role.md (added)
+++ incubator/usergrid/site/content/docs/role.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,1000 @@
+---
+title: Role
+category: docs
+layout: docs
+---
+
+Role
+====
+
+[See all application
+entities](/docs/usergrid/content/application-entities)[](/docs/usergrid/content/application-entities)
+
+A role represents a set of permissions that enable certain operations to
+be performed on a specific endpoint. You can assign a user to a role,
+and in this way give the user the permissions associated with that role.
+For further information about roles and their use, see [Managing access
+by defining permission
+rules](/managing-access-defining-permission-rules).
+
+Using App services APIs you can create, retrieve, update, delete, and
+query roles. See [Role properties](#role_prop) for a list of the
+system-defined properties for roles. In addition, you can create role
+properties specific to your application.
+
+**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.
+
+Also, the /rolenames endpoint is no longer valid. If your code currently
+makes calls to /rolenames, you need to change the calls to use /roles.
+
+Creating a new role
+-------------------
+
+Use the POST method to create a new application role.
+
+### Request URI
+
+POST /{org\_id}/{app\_id}/roles {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 | Role name and title: |
+| | |
+| | { "name" : "manager", "title" : |
+| | "Manager" } |
++--------------------------------------+--------------------------------------+
+
+### Example - Request
+
+- [cURL](#curl_create_role)
+- [JavaScript (HTML5)](#javascript_create_role)
+- [Ruby](#ruby_create_role)
+- [Node.js](#nodejs_create_role)
+
+<!-- -->
+
+ curl -X POST "https://api.usergrid.com/my-org/my-app/roles/ -d '{"name":"manager","title":"Manager"}'
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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_role name: 'manager', title: 'Manager'
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'POST',
+ endpoint:'roles',
+ body:{ name:'manager', title:'Manager' }
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â POST failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action" : "post",
+ "application" : "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "params" : {},
+ "uri" : "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "entities" : [
+ {
+ "uuid": "98e772a3-327a-11e2-aef7-02e81adcf3d0",
+ "type": "role",
+ "name": "manager",
+ "created": 1353351290724,
+ "modified": 1353351290724,
+ "inactivity": 0,
+ "metadata": {
+ "path": "/roles/98e772a3-327a-11e2-aef7-02e81adcf3d0",
+ "sets": {
+ "permissions": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/permissions"
+ },
+ "collections": {
+ "groups": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/groups",
+ "users": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users"
+ }
+ },
+ "roleName": "manager",
+ "title": "Manager"
+ }
+ ],
+ "timestamp": 1353358474917,
+ "duration": 46,
+ "duration": 45,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Getting the roles in an application
+-----------------------------------
+
+Use the GET method to get the roles for a specific application.
+
+### Request URI
+
+GET /{org\_id}/{app\_id}/roles
+
+### Parameters
+
+ Parameter Description
+ ------------------------- ----------------------------------------
+ arg uuid|string org\_id Organization UUID or organization name
+ arg uuid|string app\_id Application UUID or application name
+
+### Example - Request
+
+- [cURL](#curl_get_roles)
+- [JavaScript (HTML5)](#javascript_get_roles)
+- [Ruby](#ruby_get_roles)
+- [Node.js](#nodejs_get_roles)
+
+<!-- -->
+
+ curl -X GET "https://api.usergrid.com/my-org/my-app/roles"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ roles = app['roles'].collection
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'GET',
+ endpoint:'roles'
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â GET failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action" : "get",
+ "application" : "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "params" : {
+ "_" : [ "1328058070002" ]
+ },
+ "uri" : "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "entities" : [
+ {
+ "uuid": "70f39f36-1825-379d-8385-7a7fbe9ec74a",
+ "type": "role",
+ "name": "admin",
+ "created": 1342198809382,
+ "modified": 1350688633265,
+ "inactivity": 0,
+ "metadata": {
+ "path": "/roles/70f39f36-1825-379d-8385-7a7fbe9ec74a",
+ "sets": {
+ "permissions": "/roles/70f39f36-1825-379d-8385-7a7fbe9ec74a/permissions"
+ },
+ "collections": {
+ "groups": "/roles/70f39f36-1825-379d-8385-7a7fbe9ec74a/groups",
+ "users": "/roles/70f39f36-1825-379d-8385-7a7fbe9ec74a/users"
+ }
+ },
+ "roleName": "admin",
+ "title": "Administrator"
+ },
+ {
+ "uuid": "b8f8f336-30c9-3553-b447-6891f3e1e6bf",
+ "type": "role",
+ "name": "default",
+ "created": 1342198809472,
+ "modified": 1350688633282,
+ "inactivity": 0,
+ "metadata": {
+ "path": "/roles/b8f8f336-30c9-3553-b447-6891f3e1e6bf",
+ "sets": {
+ "permissions": "/roles/b8f8f336-30c9-3553-b447-6891f3e1e6bf/permissions"
+ },
+ "collections": {
+ "groups": "/roles/b8f8f336-30c9-3553-b447-6891f3e1e6bf/groups",
+ "users": "/roles/b8f8f336-30c9-3553-b447-6891f3e1e6bf/users"
+ }
+ },
+ "roleName": "default",
+ "title": "Default"
+ },
+ {
+ "uuid": "bd397ea1-a71c-3249-8a4c-62fd53c78ce7",
+ "type": "role",
+ "name": "guest",
+ "created": 1342198809551,
+ "modified": 1350688633299,
+ "inactivity": 0,
+ "metadata": {
+ "path": "/roles/bd397ea1-a71c-3249-8a4c-62fd53c78ce7",
+ "sets": {
+ "permissions": "/roles/bd397ea1-a71c-3249-8a4c-62fd53c78ce7/permissions"
+ },
+ "collections": {
+ "groups": "/roles/bd397ea1-a71c-3249-8a4c-62fd53c78ce7/groups",
+ "users": "/roles/bd397ea1-a71c-3249-8a4c-62fd53c78ce7/users"
+ }
+ },
+ "roleName": "guest",
+ "title": "Guest"
+ }
+ ],
+ "timestamp": 1353351684225,
+ "duration": 35,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Deleting a role
+---------------
+
+Use the DELETE method to delete the specified role and return the
+revised set of application roles.
+
+### Request URI
+
+DELETE /{org\_id}/{app\_id}/roles/{rolename}
+
+### Parameters
+
+ Parameter Description
+ ------------------------- ----------------------------------------
+ arg uuid|string org\_id Organization UUID or organization name
+ arg uuid|string app\_id Application UUID or application name
+ arg string rolename Role name
+
+### Example - Request
+
+- [cURL](#curl_delete_role)
+- [JavaScript (HTML5)](#javascript_delete_role)
+- [Ruby](#ruby_delete_role)
+- [Node.js](#nodejs_delete_role)
+
+<!-- -->
+
+ curl -X DELETE "https://api.usergrid.com/my-org/my-app/roles/manager"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ app['roles/manager'].delete
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'DELETE',
+ endpoint:'roles'
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â DELETE failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action" : "delete",
+ "application" : "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "params" : {
+ "_" : [ "1328058070002" ]
+ },
+ "path": "/roles",
+ "uri" : "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "entities": [
+ {
+ "uuid": "382d0991-74bb-3548-8166-6b07e44495ef",
+ "type": "role",
+ "name": "manager",
+ "created": 1353358474924,
+ "modified": 1353358474924,
+ "inactivity": 0,
+ "metadata": {
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef",
+ "sets": {
+ "permissions": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/permissions"
+ },
+ "collections": {
+ "groups": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/groups",
+ "users": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users"
+ }
+ },
+ "roleName": "manager",
+ "title": "Manager"
+ }
+ ],
+ "timestamp": 1353359131580,
+ "duration": 218,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Getting permissions for an application role
+-------------------------------------------
+
+Use the GET method to get permissions for the specific app role.
+
+### Request URI
+
+GET /{org\_id}/{app\_id}/roles/{rolename|role\_id}/permissions
+
+### Parameters
+
+ Parameter Description
+ --------------------------- ----------------------------------------
+ arg uuid|string org\_id Organization UUID or organization name
+ arg uuid|string app\_id Application UUID or application name
+ arg  uuid|string rolename Role UUID or role name
+
+### Example - Request
+
+- [cURL](#curl_get_role_permissions)
+- [JavaScript (HTML5)](#javascript_get_role_permissions)
+- [Ruby](#ruby_get_role_permissions)
+- [Node.js](#nodejs_get_role_permissions)
+
+<!-- -->
+
+ curl -X GET "https://api.usergrid.com/my-org/my-app/roles/manager/permissions"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ response = app['roles']['guest']['permissions'].entity
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'GET',
+ endpoint:'roles/manager/permissions'
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â GET failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action" : "get",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "uri" : "http://api.usergrid.com/your-org/your-app",
+ "entities" : [ ],
+ "data" : [ "get,post,put,delete:/**", "post:/devices", "post:/users", "put:/devices/*" ],
+ "timestamp" : 1376589421592,
+ "duration" : 89,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+Adding permissions to an application role
+-----------------------------------------
+
+Use the POST method to add permissions for the specified application
+role.
+
+### Request URI
+
+POST /{org\_id}/{app\_id}/roles/{rolename|role\_id}/permissions {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 |
++--------------------------------------+--------------------------------------+
+| arg uuid|string rolename | Role UUID or role name |
++--------------------------------------+--------------------------------------+
+| request body | JSON object with a single |
+| | permissions property. The value of |
+| | that property is a string containing |
+| | a permissions specification. The |
+| | spec is a comma-separated list of |
+| | verbs, followed by a colon, followed |
+| | by a URL pattern: |
+| | |
+| | { "permission" : "get,put,post,d |
+| | elete:/users/me/groups" } |
++--------------------------------------+--------------------------------------+
+
+### Example - Request
+
+- [cURL](#curl_add_role_permissions)
+- [JavaScript (HTML5)](#javascript_add_role_permissions)
+- [Ruby](#ruby_add_role_permissions)
+- [Node.js](#nodejs_add_role_permissions)
+
+<!-- -->
+
+ curl -X POST "https://api.usergrid.com/my-org/my-app/roles/manager/permissions" -d '{"permission":"get,put,post,delete:/users/me/groups" }'
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ app['roles/manager/permissions'].post permission:'get,put,post,delete:/users/me/groups'
+
+The example assumes use of the
+[Node.js](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'POST',
+ endpoint:'roles/manager/permissions',
+ body:{ permission:'get,put,post,delete:/users/me/groups' }
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â POST failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action" : "post",
+ "application" : "f34f4222-a166-11e2-a7f7-02e815df8rd0",
+ "params" : { },
+ "uri" : "http://api.usergrid.com/your-org/your-app",
+ "entities" : [ ],
+ "data" : [ "get,put,post,delete:/users/me/groups" ],
+ "timestamp" : 1376590904061,
+ "duration" : 21,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+Deleting permissions from an application role
+---------------------------------------------
+
+Use the DELETE method to remove permissions from the specified
+application role.
+
+### Request URI
+
+DELETE
+/{org\_id}/{app\_id}/roles/{rolename|role\_id}/permissions?permission={permissions\_spec}
+
+### Parameters
+
+ Parameter Description
+ ---------------------- ----------------------------------------------------
+ uuid|string org\_id Organization UUID or organization name
+ uuid|string app\_id Application UUID or application name
+ uuid|string rolename Role UUID or role name
+ grant\_url\_pattern The pattern on which the permissions were granted.
+
+### Example - Request
+
+- [cURL](#curl_delete_role_permissions)
+- [JavaScript (HTML5)](#javascript_delete_role_permissions)
+- [Ruby](#ruby_delete_role_permissions)
+- [Node.js](#nodejs_delete_role_permissions)
+
+<!-- -->
+
+ curl -X DELETE -H "authorization: Bearer INSERT_BEARER_TOKEN_HERE" "https://api.usergrid.com/my-org/my-app/roles/default/permissions?permission=get,post,delete:/notes"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ app['roles/manager/permission'].delete permission:'delete'
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'DELETE',
+ endpoint:'roles/manager/permission',
+ body:{ permission:'delete' }
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â DELETE failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action" : "delete",
+ "application" : "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "params" : {
+ "permission": [
+ "delete"
+ ]
+ },
+ "path": "/roles",
+ "uri" : "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+ "entities": [
+ {
+ "uuid": "382d0991-74bb-3548-8166-6b07e44495ef",
+ "type": "role",
+ "name": "manager",
+ "created": 1353359536973,
+ "modified": 1353359536973,
+ "inactivity": 0,
+ "metadata": {
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef",
+ "sets": {
+ "permissions": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/permissions"
+ },
+ "collections": {
+ "groups": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/groups",
+ "users": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users"
+ }
+ },
+ "roleName": "manager",
+ "title": "Manager"
+ }
+ ],
+ "timestamp": 1353360762403,
+ "duration": 181,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Adding a user to a role
+-----------------------
+
+Use the POST method to add a user to a role.
+
+### Request URI
+
+ POST /{org_id}/{app_id}/roles/{role_id}/users/{uuid|username}
+
+or
+
+ POST /{org_id}/{app_id}/users/{uuid|username}/roles/{role_id}
+
+### Parameters
+
+ Parameter Description
+ --------------------------- ----------------------------------------
+ arg uuid|string org\_id Organization UUID or organization name
+ arg uuid|string app\_id Application UUID or application name
+ arg uuid|string role\_id Role UUID or role name
+ arg uuid|string uuid|name User UUID or username
+
+### Example - Request
+
+- [cURL](#curl_add_role_user)
+- [JavaScript (HTML5)](#javascript_add_role_user)
+- [Ruby](#ruby_add_role_user)
+- [Node.js](#nodejs_add_role_user)
+
+<!-- -->
+
+ curl -X POST "https://api.usergrid.com/my-org/my-app/roles/manager/users/john.doe"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ app['roles/manager/users/someuser'].post nil
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'POST',
+ endpoint:'roles/manager/users/john.doe'
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â POST failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action": "post",
+ "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+ "params": {},
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users",
+ "uri": "https://api.usergrid.com/my-org/my-app/roles/382d0991-74bb-3548-8166-6b07e44495ef/users",
+ "entities": [
+ {
+ "uuid": "34e26bc9-2d00-11e2-a065-02e81ae640dc",
+ "type": "user",
+ "name": "John Doe",
+ "created": 1352748968504,
+ "modified": 1352748968504,
+ "activated": true,
+ "email": "john.doe@mail.com",
+ "metadata": {
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc",
+ "sets": {
+ "rolenames": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/rolenames",
+ "permissions": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/permissions"
+ },
+ "connections": {
+ "likes": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/likes"
+ },
+ "collections": {
+ "activities": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/activities",
+ "devices": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/devices",
+ "feed": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/feed",
+ "groups": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/groups",
+ "roles": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/roles",
+ "following": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/following",
+ "followers": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/followers"
+ }
+ },
+ "picture": "http://www.gravatar.com/avatar/90f82dba15655b8cc8e3b4d63377576f",
+ "username": "someuser"
+ }
+ ],
+ "timestamp": 1352999087337,
+ "duration": 65,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Getting the users in a role
+---------------------------
+
+Use the GET method to get the users in a role.
+
+### Request URI
+
+ GET /{org_id}/{app_id}/roles/{role_id}/users
+
+### Parameters
+
+ Parameter Description
+ -------------------------- ----------------------------------------
+ arg uuid|string org\_id Organization UUID or organization name
+ arg uuid|string app\_id Application UUID or application name
+ arg uuid|string role\_id Role UUID or role name
+
+### Example - Request
+
+- [cURL](#curl_get_role_users)
+- [JavaScript (HTML5)](#javascript_get_role_users)
+- [Ruby](#ruby_get_role_users)
+- [Node.js](#nodejs_get_role_users)
+
+<!-- -->
+
+ curl -X GET "https://api.usergrid.com/my-org/my-app/roles/manager/users"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ users = app['roles/manager/users'].collection
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'GET',
+ endpoint:'roles/manager/users'
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â GET failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action": "get",
+ "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+ "params": {
+ "_": [
+ "1352999121468"
+ ]
+ },
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users",
+ "uri": "https://api.usergrid.com/my-org/my-app/roles/382d0991-74bb-3548-8166-6b07e44495ef/users",
+ "entities": [
+ {
+ "uuid": "34e26bc9-2d00-11e2-a065-02e81ae640dc",
+ "type": "user",
+ "name": "John Doe",
+ "created": 1352748968504,
+ "modified": 1352748968504,
+ "activated": true,
+ "email": "john.doe@mail.com",
+ "metadata": {
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc",
+ "sets": {
+ "rolenames": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/rolenames",
+ "permissions": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/permissions"
+ },
+ "connections": {
+ "likes": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/likes"
+ },
+ "collections": {
+ "activities": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/activities",
+ "devices": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/devices",
+ "feed": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/feed",
+ "groups": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/groups",
+ "roles": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/roles",
+ "following": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/following",
+ "followers": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/followers"
+ }
+ },
+ "picture": "http://www.gravatar.com/avatar/90f823ba15655b8cc8e3b4d63377576f",
+ "username": "john.doe"
+ }
+ ],
+ "timestamp": 1352999119136,
+ "duration": 28,
+ "organization": "my-org",
+ "applicationName": "my-app"
+
+Deleting a user from a role
+---------------------------
+
+Use the DELETE method to delete a user from a role.
+
+### Request URI
+
+ DELETE /{org_id}/{app_id}/roles/{role_id}/users/{uuid|username}
+
+### Parameters
+
+ Parameter Description
+ --------------------------- ----------------------------------------
+ arg uuid|string org\_id Organization UUID or organization name
+ arg uuid|string app\_id Application UUID or application name
+ arg uuid|string role\_id Role UUID or role name
+ arg uuid|string uuid|name User UUID or username
+
+### Example - Request
+
+- [cURL](#curl_delete_role_user)
+- [JavaScript (HTML5)](#javascript_delete_role_user)
+- [Ruby](#ruby_delete_role_user)
+- [Node.js](#nodejs_delete_role_user)
+
+<!-- -->
+
+ curl -X DELETE "https://api.usergrid.com/my-org/my-app/roles/manager/users/john.doe"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+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/'
+ app['roles/manager/users/john.doe'].delete
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+ var options = {
+ method:'DELETE',
+ endpoint:'roles/manager/users/john.doe'
+ };
+ client.request(options, function (err, data) {
+ if (err) {
+ //error â DELETE failed
+ } else {
+ //success â data will contain raw results from API call
+ }
+ });
+
+### Example - Response
+
+ {
+ "action": "delete",
+ "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+ "params": {
+ "_": [
+ "1353000719265"
+ ]
+ },
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users",
+ "uri": "equest
+ curl -X DELETE "https://api.usergrid.com/my-org/my-app/roles/382d0991-74bb-3548-8166-6b07e44495ef/users",
+ "entities": [
+ {
+ "uuid": "34e26bc9-2d00-11e2-a065-02e81ae640dc",
+ "type": "user",
+ "name": "John Doe",
+ "created": 1352748968504,
+ "modified": 1352748968504,
+ "activated": true,
+ "email": "john.doe@mail.com",
+ "metadata": {
+ "path": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc",
+ "sets": {
+ "rolenames": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/rolenames",
+ "permissions": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/permissions"
+ },
+ "connections": {
+ "likes": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/likes"
+ },
+ "collections": {
+ "activities": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/activities",
+ "devices": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/devices",
+ "feed": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/feed",
+ "groups": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/groups",
+ "roles": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/roles",
+ "following": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/following",
+ "followers": "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/followers"
+ }
+ },
+ "picture": "http://www.gravatar.com/avatar/90f823ba13655b8cc8e3b4d63377576f",
+ "username": "john.doe"
+ }
+ ],
+ "timestamp": 1353000717531,
+ "duration": 338,
+ "organization": "my-org",
+ "applicationName": "my-app"
+ }
+
+Role properties
+---------------
+
+The following are the system-defined properties for role entities. You
+can create application-specific properties for a role 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
+role entity. In addition the roles name is reserved for the roles
+collection â you can't use it to name another collection.
+
+The look-up property for a role is name that is, you can use the name
+property to reference a role in an API call. However, you can search on
+a role using any property of the role entity. See\
+
+Nonexistent node nid: 9321.
+
+for details on searching.
+
+### General properties
+
+Roles have the following general properties.
+
+ Property Type Description
+ ---------- -------- ---------------------------------------------------------------------------------
+ uuid UUID Roleâs unique entity ID
+ type string "role"
+ 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 Unique name identifying the role (mandatory)
+ roleName string Informal role name
+ title string Role title
+
+### Set properties
+
+Roles have the following set property.
+
+ Set Type Description
+ ------------- -------- -------------------------
+ permissions string Set of user permissions
+
+### Collection properties
+
+Roles have the following collections.
+
+ Collection Type Description
+ ------------ ------- -----------------------------------------
+ users user Collection of users assigned to a role
+ groups group Collection of groups assigned to a role
+
+Â
Added: incubator/usergrid/site/content/docs/ruby-gem.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/ruby-gem.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/ruby-gem.md (added)
+++ incubator/usergrid/site/content/docs/ruby-gem.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,28 @@
+---
+title: Ruby gem
+category: docs
+layout: docs
+---
+
+Installation
+------------
+
+From the command-line run:
+
+```bash
+$ gem install usergrid_iron
+```
+
+Organizations
+-------------
+
+````ruby
+# Initialize Management object
+mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
+
+# Create a new Organization
+mgmt.create_organization 'testorg', 'test123', 'test', 'tester123@hotmail.com', 'test12345'
+
+# Load an exiting Organization
+org = mgmt.organization 'testorg'
+````
\ No newline at end of file
Added: incubator/usergrid/site/content/docs/securing-your-app.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/securing-your-app.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/securing-your-app.md (added)
+++ incubator/usergrid/site/content/docs/securing-your-app.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,83 @@
+---
+title: Securing your app
+category: docs
+layout: docs
+---
+
+Securing your app
+=================
+
+There a number of actions you should take to ensure that your app is
+secure before you put it into production.
+
+Review permissions in your apps
+-------------------------------
+
+Prior to launching your app into a production environment, it is
+advisable to review all the roles and permissions you have set up.
+During development, you may find that you added various permissions
+which may or may not still be required once the app is complete. Review
+all permissions and delete any that are no longer required.
+
+Also make sure that you review the roles and permissions that are set up
+for the sandbox app. By default, every new Apache Usergrid account has an
+app named âsandboxâ that is already created under your new organization.
+This app is no different than any other app that you might create,
+except that the Guest role has been given full permissions (that is,
+/\*\* for GET, POST, PUT, and DELETE). This eliminates the need for a
+token when making application level calls, and can make it much easier
+to get your app up and running.
+
+Prior to taking your app live, you should secure it by removing any
+Guest permissions for /\*\*. (See [Managing access by defining
+permission rules](/managing-access-defining-permission-rules) for
+further information about setting permissions.) After you secure your
+the app, any calls to the API will need to include an OAuth token. Oauth
+tokens (also called access tokens) are obtained by the API in response
+to successful authentication calls. Your app saves the token and uses it
+for all future calls during that session. Learn more about access tokens
+in [Authenticating users and application
+clients](/authenticating-users-and-application-clients).
+
+Review test accounts
+--------------------
+
+If you created any test user or test administrator accounts during
+development, these should also be reviewed for relevancy and security.
+Delete any test accounts that are no longer needed. If these accounts
+are still needed, make sure that passwords have been secured to the
+standards required by your app.
+
+Use https
+---------
+
+Make sure that any calls you make to the API are done using the secure
+https protocol, and not the insecure http protocol. The proper
+application endpoint is: https://api.usergrid.com
+
+If your app is a web app, that is, an app served by a web server, make
+sure that the app is served using https.
+
+Acquire access tokens in a secure way
+-------------------------------------
+
+There are various methods for acquiring an access token (see
+[Authenticating users and application
+clients](/authenticating-users-and-application-clients)). One method is
+to use the application or organization level client secret-client id
+combination. This method should not be used in client applications (this
+is, apps that are deployed to a device, and which authenticate and make
+calls against the API).
+
+Thatâs because a hacker could analyze your app (even a compiled, binary
+distribution of your app), and retrieve the secret-id combination. Armed
+with this information, an attacker could gain full access to the data in
+your account.
+
+Instead, use application user credentials. This means that your appâs
+users should provide a username and password. Your app would use these
+to authenticate against the API and retrieve an access token.
+
+The client secret-client id combination should be used only in secure,
+server-side applications where there is no possibility of a hacker
+gaining control of the credentials.
Added: incubator/usergrid/site/content/docs/security-model.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/security-model.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/security-model.md (added)
+++ incubator/usergrid/site/content/docs/security-model.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,40 @@
+---
+title: App services security model
+category: docs
+layout: docs
+---
+
+App services security model
+===========================
+
+This section contains information about the security model in App
+services. It describes how App services performs authentication and
+mediates access to resources.
+
+As described in these pages, App services rely on OAuth 2.0 for
+authentication, basing data access decisions on tokens supplied with
+each API request. Appropriate credentials are necessary to generate
+these tokens. Access to App services entities is further restricted by
+assigned roles and permissions.
+
+- [Authentication and access in App
+ services](/authentication-and-access-app-services-0)
+ - [Access
+ types](/usergrid/content/authentication-and-access-usergrid#access_types)
+ - [Applications](/usergrid/content/authentication-and-access-usergrid#applications)
+ - [Application
+ users](/usergrid/content/authentication-and-access-usergrid#application_users)
+ - [Using an access
+ token](/usergrid/content/authentication-and-access-usergrid#access_token)
+ - [Safe mobile
+ access](/usergrid/content/authentication-and-access-usergrid#safe_mobile)
+
+- [Managing access by defining permission
+ rules](/managing-access-defining-permission-rules)
+ - [Roles](/usergrid/content/roles-and-permissions-usergrid#roles)
+ - [Permissions](/usergrid/content/roles-and-permissions-usergrid#permissions)
+
+- Nonexistent node nid: 302.
+ - [authentication](/usergrid/content/facebook-sign)
+
+
Added: incubator/usergrid/site/content/docs/updating-collections.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/updating-collections.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/updating-collections.md (added)
+++ incubator/usergrid/site/content/docs/updating-collections.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,436 @@
+---
+title: Updating Collections
+category: docs
+layout: docs
+---
+
+Updating Collections
+====================
+
+This article describes how to perform batch updates on all entities in a
+collection. Batch updates require the use of a query string in the
+request, which can either specify all entities in the collection or a
+subset of entities for the update to be performed on. For more
+information on queries, see [Basic query syntax](/basic-query-syntax).
+
+**Note:** Although not shown in the API examples below, you need to
+provide a valid access token with each API call. See [Authenticating
+users and application
+clients](/authenticating-users-and-application-clients) for details.
+
+Batch updating entities in a collection
+---------------------------------------
+
+- [cURL](#curl_update_collection)
+- [iOS](#ios_update_collection)
+- [Android](#android_update_collection)
+- [JavaScript (HTML5)](#javascript_update_collection)
+- [Ruby](#ruby_update_collection)
+- [Node.js](#nodejs_update_collection)
+
+### Example Request/Response
+
+#### Request:
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app/items/?ql= -d '{"availability":"in-stock"}'
+
+Note the empty `?ql=` query string.
+
+#### Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### Request Syntax
+
+ curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/?ql= -d {<property>}
+
+Note the empty query string (ql=) appended to the URL.
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| org | Organization UUID or organization |
+| | name |
++--------------------------------------+--------------------------------------+
+| app | Application UUID or application name |
++--------------------------------------+--------------------------------------+
+| collection | Collection UUID or collection name |
++--------------------------------------+--------------------------------------+
+| property | An entity property to be updated, |
+| | formatted as a key-value pair. For |
+| | example: |
+| | |
+| | {"property_1":"value_1", "proper |
+| | ty_2":"value_2",...} |
++--------------------------------------+--------------------------------------+
+
+This example uses the [Apache Usergrid iOS SDK](/app-services-sdks#ios).
+
+### Example Request/Response
+
+#### Request:
+
+ -(NSString*)updateCollection {
+
+ NSString *url = @"https://api.usergrid.com/your-org/your-app/items/?ql";
+ NSString *op = @"PUT";
+ NSString *opData = @"{\"availability\":\"in-stock\"}"; //we escape the quotes
+
+ //we recommend you call ApigeeClient from your AppDelegate.
+ //for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
+ //create an instance of AppDelegate
+ AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate];
+
+ //call createEntity to initiate the API call
+ ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData];
+
+ @try {
+ //success
+ }
+ @catch (NSException * e) {
+ //fail
+ }
+
+ }
+
+
+#### Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### SDK Method
+
+ (ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData
+
+### Properties
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| url | A fully-formed request url in the |
+| | following format: |
+| | https://api.usergrid.com/<org>/< |
+| | app>/<collection>/?ql= |
+| | |
+| | Note that you must include an empty |
+| | '?ql=' query string at the end of |
+| | the URL |
++--------------------------------------+--------------------------------------+
+| op | The HTTP method - in this case, |
+| | 'PUT' |
++--------------------------------------+--------------------------------------+
+| opData | A JSON-formatted string that |
+| | contains the entity properties to be |
+| | updated |
++--------------------------------------+--------------------------------------+
+
+Updating all entities in a collection is not currently supported by the
+[Apache Usergrid Android SDK](/app-services-sdks#android).
+
+This example uses the [Apache Usergrid JavaScript (HTML5)
+SDK](/app-services-sdks#javascript).
+
+### Example Request/Response
+
+#### Request:
+
+ //create the basic client object
+ var dataClient = new Usergrid.Client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //options for the request
+ var options = {
+ endpoint:"items/?ql=", //don't forget to append '/?ql='
+ method:"PUT",
+ body: {"availability":"in-stock"}
+ }
+
+ dataClient.request(options,function (error,response) {
+
+ if (error) {
+ // Error
+ } else {
+ // Success
+ }
+
+ });
+
+
+#### Response:
+
+ Object {action: "put", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"â¦}
+ action: "put"
+ application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
+ applicationName: "your-app"
+ duration: 92
+ entities: Array[2]
+ 0: Object
+ availability: "in-stock"
+ created: 1378852309294
+ modified: 1378853303215
+ name: "milk"
+ price: "3.25"
+ type: "item"
+ uuid: "c86ffbf0-1a68-11e3-ab22-3713e5fcf9d2"
+ __proto__: Object
+ 1: Object
+ availability: "in-stock"
+ created: 1378852309373
+ modified: 1378853303256
+ name: "bread"
+ price: "4.00"
+ type: "item"
+ uuid: "c87be2da-1a68-11e3-80f4-975f1f8b1f86"
+ __proto__: Object
+ length: 2
+ __proto__: Array[0]
+ organization: "your-org"
+ params: Object
+ path: "/items"
+ timestamp: 1378853303201
+ uri: "http://api.usergrid.com/your-org/your-app/items"
+ __proto__: Object
+
+
+### SDK Method
+
+ request(options, callback)
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| options | A JSON-formatted object containing |
+| | the following properties: |
+| | |
+| | - endpoint: the UUID or name of |
+| | the collection to be updated, |
+| | appended by an empty query |
+| | string in the format: |
+| | \<collection\>/?ql= |
+| | - method: the HTTP method for the |
+| | request â in this case `PUT` |
+| | - body: the body of the request |
+| | that specifies the properties to |
+| | be updated in JSON format |
++--------------------------------------+--------------------------------------+
+| callback | Callback function to handle the API |
+| | response |
++--------------------------------------+--------------------------------------+
+
+This example uses the [Apache Usergrid RubyGem](/app-services-sdks#ruby).
+
+### Example Request/Response
+
+#### Request:
+
+ #Create a client object
+ usergrid_api = 'https://api.usergrid.com'
+ organization = 'your-org'
+ application = 'your-app'
+
+ client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"
+
+ begin
+ collection = client['items'].collection
+ collection.update_query({availability: 'in-stock'},"")
+ rescue
+ #fail
+ end
+
+
+#### Response:
+
+ {
+ "action" : "put",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "ql" : [ "" ]
+ },
+ "path" : "/items",
+ "uri" : "http://api.usergrid.com/your-org/your-app/items",
+ "entities" : [ {
+ "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
+ "type" : "item",
+ "name" : "milk",
+ "price" : "3.25",
+ "availability" : "in-stock"
+ "created" : 1378849479113,
+ "modified" : 1378849567301,
+ "name" : "milk",
+ }, {
+ "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
+ "type" : "item",
+ "name" : "bread",
+ "price" : "4.00",
+ "availability" : "in-stock"
+ "created" : 1378849479206,
+ "modified" : 1378849567351,
+ "name" : "bread",
+ } ],
+ "timestamp" : 1378849567280,
+ "duration" : 207,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+### SDK Method
+
+ collection.update_query(properties, query_string)
+
+### Properties
+
+ Parameter Description
+ --------------- --------------------------------------------------------------------------------------------------------------
+ properties JSON-formatted string that contains the entity properties to be updated
+ query\_string A query string that specifies the entities to be updated. Use an empty string (`""`) to update all entities.
+
+The example assumes use of the [Apache Usergrid Node.js
+module](/app-services-sdks#nodejs).
+
+### Example Request/Response
+
+#### Request:
+
+ //Create the Apache Usergrid client object
+ var dataClient = new Usergrid.client({
+ orgName:'your-org',
+ appName:'your-app'
+ });
+
+ //Specify the options for the request
+ var options = {
+ endpoint:"items/?ql=", //don't forget to append '/?ql='
+ method:"PUT",
+ body: {"availability":"in-stock"}
+ }
+
+ dataClient.request(options,function (error,response) {
+
+ if (error) {
+ //error
+ } else {
+ //success
+ }
+
+ });
+
+
+#### Response:
+
+ { action: 'put',
+ application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
+ params: { ql: [ '' ] },
+ path: '/items',
+ uri: 'http://api.usergrid.com/your-org/your-app/items',
+ entities:
+ [ { uuid: 'c86ffbf0-1a68-11e3-ab22-3713e5fcf9d2',
+ type: 'item',
+ name: 'milk',
+ created: 1378852309294,
+ modified: 1378855073613,
+ availability: 'in-stock' },
+ { uuid: 'c87be2da-1a68-11e3-80f4-975f1f8b1f86',
+ type: 'item',
+ name: 'bread',
+ created: 1378852309373,
+ modified: 1378855073655,
+ availability: 'in-stock' } ],
+ timestamp: 1378855073595,
+ duration: 106,
+ organization: 'your-org',
+ applicationName: 'your-app' }
+
+
+### SDK Method
+
+ request(options,callback);
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter | Description |
++======================================+======================================+
+| options | A JSON-formatted object containing |
+| | the following properties: |
+| | |
+| | - endpoint: the UUID or name of |
+| | the collection to be updated, |
+| | appended by an empty query |
+| | string in the format: |
+| | \<collection\>/?ql= |
+| | - method: the HTTP method for the |
+| | request, in this case *PUT* |
++--------------------------------------+--------------------------------------+
+| callback | Callback function to handle the API |
+| | response |
++--------------------------------------+--------------------------------------+
+
+Â