Added: incubator/usergrid/site/publish/docs/group/index.html URL: http://svn.apache.org/viewvc/incubator/usergrid/site/publish/docs/group/index.html?rev=1542910&view=auto ============================================================================== --- incubator/usergrid/site/publish/docs/group/index.html (added) +++ incubator/usergrid/site/publish/docs/group/index.html Mon Nov 18 06:09:23 2013 @@ -0,0 +1,1217 @@ + + + + + + Apache Usergrid (incubating) — Group + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+
+ + +

Group

+

A group entity organizes users into a group. Using Apache Usergrid APIs you can create, retrieve, update, or delete a group. You can also add or delete a user to or from a group.

+

See Group entity properties for a list of the system-defined properties for group entities. In addition, you can create group 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 for details.

+

Creating a new group

+

Use the POST method to create a new group. Groups use paths to indicate their unique names. This allows you to create group hierarchies by using slashes. For this reason, you need to specify a path property for a new group.

+

Request URI

+

POST /{org_id}/{app_id}/groups

+

Parameters

+ + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name

Example - Request

+
curl -X POST "https://api.usergrid.com/my-org/my-app/groups" -d '{"path":"mynewgroup"}'
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'POST',
+    endpoint:'groups',
+    body:{ path:'mynewgroup' }
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+app['groups'].post path: 'mynewgroup'
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'POST',
+    endpoint:'groups',
+    body:{ path:'mynewgroup' }
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+"action": "post",
+"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+"params": {},
+"path": "/groups",
+"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups",
+
+"entities": [
+    {
+      "uuid": "a668717b-67cb-11e1-8223-12313d14bde7",
+      "type": "group",
+      "created": 1331066016571,
+      "modified": 1331066016571,
+      "metadata": {
+        "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7",
+        "sets": {
+          "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/rolenames",
+          "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/permissions"
+        },
+        "collections": {
+          "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/activities",
+          "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/feed",
+          "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/roles",
+          "users": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users"
+        }
+      },
+      "path": "mynewgroup"
+    }
+ ],
+"timestamp": 1331066016563,
+"duration": 35,
+"organization" : "my-org",
+"applicationName": "my-app"
+}
+

Adding a user to a group

+

Use the POST method to add a user to a group. If the named group does not yet exist, an error message is returned.

+

Request URI

+

POST /{org_id}/{app_id}/groups/{uuid|groupname}/users/{uuid|username}

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group
arg uuid|string usernameUUID or username of user

Example - Request

+
curl -X POST "https://api.usergrid.com/my-org/my-app/groups/mynewgroup/users/john.doe"
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'POST',
+    endpoint:'groups/mynewgroup/users/john.doe'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+app['groups/mynewgroup/users/john.doe'].post nil
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'POST',
+    endpoint:'groups/mynewgroup/users/john.doe'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+"action": "post",
+"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+"params": {},
+"path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users",
+"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups/a668717b-67cb-11e1-8223-12313d14bde7/users",
+
+"entities": [
+      {
+        "uuid": "6fbc8157-4786-11e1-b2bd-22000a1c4e22",
+        "type": "user",
+        "nanme": "John Doe",
+        "created": 1327517852364015,
+        "modified": 1327517852364015,
+        "activated": true,
+        "email": "john.doe@mail.com",
+        "metadata": {
+          "connecting": {
+            "owners":   "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/connecting/owners"
+             },
+          "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22",
+          "sets": {
+            "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/rolenames",
+            "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/permissions"
+             },
+          "collections": {
+            "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/activities",
+            "devices": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/devices",
+            "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/feed",
+            "groups": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/groups",
+            "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/roles",
+            "following": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/following",
+            "followers": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/followers"
+             }
+        },
+        "picture": "https://www.gravatar.com/avatar/90f823ba15655b8cc8e3b4d63377576f",
+        "username": "john.doe"
+      }
+   ],
+   "timestamp": 1331066031380,
+   "duration": 64,
+   "organization" : "my-org",
+   "applicationName": "my-app"
+}
+

Getting a group

+

Use the GET method to retrieve a group.

+

Request URI

+

GET /{org_id}/{app_id}/groups/{uuid|groupname}

+

Parameters

+ + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group

Example - Request

+
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mynewgroup"
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'GET',
+    endpoint:'groups/mynewgroup'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+user = app['mynewgroup'].entity
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'GET',
+    endpoint:'groups/mynewgroup'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+"action": "get",
+"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+"params": {
+      "_": [
+        "1331066049869"
+      ]
+},
+"path": "/groups",
+"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups",
+
+"entities": [
+    {
+      "uuid": "a668717b-67cb-11e1-8223-12313d14bde7",
+      "type": "group",
+      "created": 1331066016571,
+      "modified": 1331066016571,
+      "metadata": {
+        "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7",
+        "sets": {
+          "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/rolenames",
+          "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/permissions"
+        },
+        "collections": {
+          "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/activities",
+          "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/feed",
+          "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/roles",
+          "users": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users"
+        }
+      },
+      "path": "mynewgroup"
+    }
+],
+"timestamp": 1331066050106,
+"duration": 18,
+"organization" : "my-org",
+"applicationName": "my-app"
+}
+

Updating a group

+

Use the PUT method to update a group.

+

Request URI

+

PUT /{org_id}{app_id}/groups/{uuid|groupname} {request body}

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group
request bodySet of entity properties

Example - Request

+
curl -X PUT "https://api.usergrid.com/my-org/my-app/groups/mynewgroup" -d '("foo":"bar"}'
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'PUT',
+    endpoint:'groups/mynewgroup',
+    body:{ foo:'bar' }
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+mynewgroup = app['groups/mynewgroup'].put foo: 'bar'
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'PUT',
+    endpoint:'groups/mynewgroup',
+    body:{ foo:'bar' }
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+"action": "put",
+"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+"params": {},
+"path": "/groups",
+"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups",
+
+"entities": [
+    {
+      "uuid": "a668717b-67cb-11e1-8223-12313d14bde7",
+      "type": "group",
+      "created": 1331066016571,
+      "modified": 1331066092191,
+      "foo": "bar",
+      "metadata": {
+        "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7",
+        "sets": {
+          "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/rolenames",
+          "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/permissions"
+        },
+        "collections": {
+          "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/activities",
+          "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/feed",
+          "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/roles",
+          "users": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users"
+        }
+      },
+      "path": "mynewgroup"
+    }
+],
+"timestamp": 1331066092178,
+"duration": 31,
+"organization" : "my-org",
+"applicationName": "my-app"
+}
+

Deleting a user from a group

+

Use the DELETE method to delete a user from the specified group.

+

Request URI

+

DELETE /{org_id}/{app_id}/groups/{uuid|groupname}/users/{uuid|username}

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group
arg uuid|string usernameUUID or username of user to be deleted

cURL Example - Request

+
curl -X DELETE "https://api.usergrid.com//my-org/my-app/groups/mynewgroup/users/john.doe"
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'DELETE',
+    endpoint:'groups/mynewgroup/users/john.doe'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+app['groups/mynewgroup/users/john.doe'].delete
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'DELETE',
+    endpoint:'groups/mynewgroup/users/john.doe'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+"action": "delete",
+"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+"params": {
+      "_": [
+        "1331066118009"
+      ]
+},
+"path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users",
+"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups/a668717b-67cb-11e1-8223-12313d14bde7/users",
+
+"entities": [
+      {
+        "uuid": "6fbc8157-4786-11e1-b2bd-22000a1c4e22",
+        "type": "user",
+        "name": "John Doe",
+        "created": 1327517852364015,
+        "modified": 1327517852364015,
+        "activated": true,
+        "email": "john.doe@mail.com",
+        "metadata": {
+          "connecting": {
+            "owners": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/connecting/owners"
+          },
+          "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22",
+          "sets": {
+            "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/rolenames",
+            "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/permissions"
+          },
+          "collections": {
+            "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/activities",
+            "devices": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/devices",
+            "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/feed",
+            "groups": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/groups",
+            "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/roles",
+            "following": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/following",
+            "followers": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/followers"
+          }
+        },
+        "picture": "https://www.gravatar.com/avatar/90f823ba15655b8cc8e3b4d63377576f",
+        "username": "john.doe"
+      }
+],
+"timestamp": 1331066118193,
+"duration": 236,
+"organization" : "my-org",
+"applicationName": "my-app"
+}
+

Deleting a group

+

Use the DELETE method to delete a group.

+

Request URI

+

DELETE /{org_id}/{app_id}/groups/{uuid|groupname}

+

Parameters

+ + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group

Example - Request

+
curl -X DELETE "https://api.usergrid.com//my-org/my-app/groups/mynewgroup"
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'DELETE',
+    endpoint:'groups/mynewgroup'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+app['groups/mynewgroup'].delete
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'DELETE',
+    endpoint:'groups/mynewgroup'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+"action": "delete",
+"application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
+"params": {
+    "_": [
+      "1331066144280"
+    ]
+},
+"path": "/groups",
+"uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups",
+
+"entities": [
+    {
+      "uuid": "a668717b-67cb-11e1-8223-12313d14bde7",
+      "type": "group",
+      "created": 1331066016571,
+      "modified": 1331066092191,
+      "foo": "bar",
+      "metadata": {
+        "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7",
+        "sets": {
+          "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/rolenames",
+          "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/permissions"
+        },
+        "collections": {
+          "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/activities",
+          "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/feed",
+          "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/roles",
+          "users": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users"
+        }
+      },
+      "path": "mynewgroup"
+    }
+],
+"timestamp": 1331066144462,
+"duration": 302,
+"organization" : "my-org",
+"applicationName": "my-app"
+}
+

Getting a group’s feed

+

Use the GET method to retrieve the feed for a group. This gets a list of all the activities that have been posted to this group, that is, the activities for which this group has a relationship (owns).

+

Request URI

+

GET /{org_id}/{app_id}/groups/{uuid|groupname}/feed

+

Parameters

+ + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group

Example - Request

+
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mygroup/feed"
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'GET',
+    endpoint:'groups/mygroup/feed'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+activities = app['groups/mygroup/feed'].collection
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'GET',
+    endpoint:'groups/mygroup/feed'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+    "action": "get",
+    "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+    "params":  {},
+    "path": "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/feed",
+    "uri": "https://api.usergrid.com/my-org/my-app/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/feed",
+    "entities":  [
+       {
+        "uuid": "563f5d96-37f3-11e2-a0f7-02e81ae640dc",
+        "type": "activity",
+        "created": 1353952903811,
+        "modified": 1353952903811,
+        "actor":  {
+          "displayName": "John Doe",
+          "image":  {
+            "duration": 0,
+            "height": 80,
+            "url": "http://www.gravatar.com/avatar/",
+            "width": 80
+          },
+          "uuid": "1f3567aa-da83-11e1-afad-12313b01d5c1",
+          "email": "john.doe@gmail.com",
+        "username": "john.doe"
+        },
+        "content": "Hello World!",
+        "metadata":  {
+          "cursor": "gGkAAQMAgGkABgE7PeHCgwCAdQAQVj9dljfzEeKg9wLoGuZA3ACAdQAQVkVRCTfzEeKg9wLoGuZA3AA",
+          "path": "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/feed/563f5d96-37f3-11e2-a0f7-02e81ae640dc"
+        },
+        "published": 1353952903811,
+        "verb": "post"
+      }
+    ],
+  "timestamp": 1353953272756,
+  "duration": 29,
+  "organization": "my-org",
+  "applicationName": "my-app"
+

Getting all users in a group

+

Use the GET method to retrieve all the users in a group.

+

Request URI

+

GET /{org_id}/{app_id}/groups/{uuid|groupname}/users

+

Parameters

+ + + + + + + + + + + + + + + + + + + +
ParameterDescription
arg uuid|string org_idOrganization UUID or organization name
arg uuid|string app_idApplication UUID or application name
arg uuid|string groupnameUUID or name of the group

Example - Request

+
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mygroup/users"
+

The example assumes use of the JavaScript (HTML5) SDK.

+
var options = {
+    method:'GET',
+    endpoint:'groups/mygroup/users'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

The example assumes use of the Ruby SDK.

+
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
+activities = app['groups/mygroup/users'].collection
+

The example assumes use of the Node.js module.

+
var options = {
+    method:'GET',
+    endpoint:'groups/mygroup/users'
+};
+client.request(options, function (err, data) {
+    if (err) {
+        //error
+    } else {
+        //success - data will contain raw results from API call
+    }
+});
+

Example - Response

+
{
+  "action" : "get",
+  "application" : "e7127751-6985-11e2-8078-02e81aeb2129",
+  "params" : { },
+  "path" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users",
+  "uri" : "http://api.usergrid.com/myorg/sandbox/groups/d20976ff-802f-11e2-b690-02e81ae61238/users",
+  "entities" : [ {
+    "uuid" : "cd789b00-698b-11e2-a6e3-02e81ae236e9",
+    "type" : "user",
+    "name" : "barney",
+    "created" : 1359405994314,
+    "modified" : 1361894320470,
+    "activated" : true,
+    "email" : "barney@apigee.com",
+    "metadata" : {
+      "path" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9",
+      "sets" : {
+        "rolenames" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/rolenames",
+        "permissions" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/permissions"
+      },
+      "collections" : {
+        "activities" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/activities",
+        "devices" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/devices",
+        "feed" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/feed",
+        "groups" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/groups",
+        "roles" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/roles",
+        "following" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/following",
+        "followers" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/followers"
+      }
+    },
+    "name" : "barney",
+    "picture" : "http://www.gravatar.com/avatar/00767101f6b4f2cf5d02ed510dbcf0b4",
+    "test" : "fred",
+    "username" : "barney"
+  } ],
+  "timestamp" : 1361903248398,
+  "duration" : 24,
+  "organization" : "myorg",
+  "applicationName" : "sandbox"
+}
+

Group properties

+

The following are the system-defined properties for group entities. The system-defined properties are reserved. You cannot use these names to create other properties for a group entity. In addition the groups name is reserved for the group collection — you can’t use it to name another collection.

+

The look-up properties for the entities of type group are UUID and path, that is, you can use the uuid or path property to reference a group in an API call. However, you can search on a group using any property of the group entity. See Queries and parameters for details on searching.

+

General properties

+

Groups have the following general properties.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
uuidUUIDGroup’s unique entity ID
typestringType of entity, in this case “user”
createdlong +UNIX timestamp of entity creation
modifiedlong +UNIX timestamp of entity modification
pathstringValid slash-delimited group path (mandatory)
titlestringDisplay name

Set properties

+

Groups have the following set properties.

+ + + + + + + + + + + + + + + + + + + + + + + +
SetTypeDescription
connectionsstringSet of connection types (e.g., likes)
rolenamesstringSet of roles assigned to a group
credentialsstringSet of group credentials

Collections

+

Groups have the following collections.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CollectionTypeDescription
usersuserCollection of users in the group
activitiesactivityCollection of activities a user has performed
feedactivityInbox of activity notifications a group has received
rolesroleSet of roles to which a group belongs

 

+
+
+
+
+
+
+
+ Questions? Please do ask on the mailing-list!
+ Found an error? We’d greatly appreciate a pull request about this article on github.
+
+
+
+ + + + + + + + + + + \ No newline at end of file Added: incubator/usergrid/site/publish/docs/html-5-example-messagee/index.html URL: http://svn.apache.org/viewvc/incubator/usergrid/site/publish/docs/html-5-example-messagee/index.html?rev=1542910&view=auto ============================================================================== --- incubator/usergrid/site/publish/docs/html-5-example-messagee/index.html (added) +++ incubator/usergrid/site/publish/docs/html-5-example-messagee/index.html Mon Nov 18 06:09:23 2013 @@ -0,0 +1,391 @@ + + + + + + Apache Usergrid (incubating) — Messagee Example + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+
+ + +

Messagee Example

+

Messagee is a simple Twitter-style messaging application that leverages the extensive functionality of App services. This section describes some of the features of Messagee.

+

There are three client versions of Messagee:

+

The sections below describe how to create a new app, enter some test users, and run the app. You also learn how to use the App services admin portal, a user interface that streamlines data and application management in the App services system. The portal is also a reference application that shows how to incorporate App services APIs with JavaScript. For a more detailed discussion of the portal’s functionality, see Admin portal.

+

Creating a user account in App services

+

Go to https://apigee.com/usergrid/ to access the login screen for the App services admin portal. If you are new to App services, sign up for an account to access the portal, specifying an organization (e.g., the name of your company or project team) and a username and password that you can use to authenticate. Because App services are designed for use by development teams, the same username can be associated with one or more organizations.

+

If you create a new account, you receive a confirmation email that contains a URL that you must click to activate the account. After this, simply log in to the portal with your username and password.

+
+ +
+

Creating an app and users

+

When you have logged in, you need to create a new application.

+
+ +
+
    +
  1. +
      +
    1. Enter a unique application name. The name must be unique to avoid a conflict with another user running the same application.
    2. +
    +
    + +
    +
  2. +
  3. +
      +
    1. Make sure that the portal shows the application name you entered as the active application beneath the Applications menu (1).
    2. +
    +

    If the correct name is not displayed, click the menu and select your application.

    +

    Next, you need to populate a test user user-test-1 that is going to log in to your copy of the server-side Messagee app.

    +
  4. +
  5. +
      +
    1. Click the Users box on the left side of the console (2).
    2. +
    +
    + +
    +
  6. +
  7. +
      +
    1. Click the Add button and enter the user information for your application in the pop-up window (be sure to create a password you can remember), and then click the Create button. Repeat these steps to create a second username test-user-2.
    2. +
    +
    + +
    +
  8. +

9.

+

When you have finished all these steps, you have a new application and two new users.

+
+ +
+

Now that you have created a uniquely named copy of the Messagee application as well as two user accounts (test-user-1 and test-user-2), you are ready to test out the Messagee app. Use test-user-1 to log in to the app, and test-user-2 as the user to follow.

+

To continue with the example, follow the instructions for a client app (iOS client, Android client, or HTML5 client).

+

iOS client

+

Messagee is available as an iPhone app that uses Apache Usergrid and RestKit. The source for the iOS version of Messagee is available in the /samples/messagee directory of the Apache Usergrid iOS SDK

+

Here are the steps to run the Messagee app on iOS:

+
    +
  1. +
      +
    1. Run Steps 1-6 under Creating an app and users.
    2. +
    +

    These steps create a unique instance of the Messagee app on the server and two test users, test-user-1 and test-user-2.

    +
  2. +
  3. +
      +
    1. Access the Messagee server app by typing a URL similar to the following into your iOS mobile client (replace <Messagee> with the unique name of your application):
    2. +
    +

    https://api.usergrid.com/<Messagee>/index.html

    +
    + +
    +
  4. +
  5. +
      +
    1. On the mobile client, complete the registration information and click Register.
    2. +
    +
    + +
    +
  6. +
  7. +
      +
    1. Log in to the Messagee app by entering the test-user-1 account information created previously, and click the Sign in button.
    2. +
    +
    + +
    +

    At this point, the message board is empty:

    +
    + +
    +
  8. +
  9. +
      +
    1. To post a message using the app, click the top-right icon in the message board to create a message, write the message text, and send it by clicking Post.
    2. +
    +
    + +
    +

    Note: The posted message should appear in the message board within few seconds.

    +
    + +
    +

    For your instance of the Messagee application to act like Twitter, you need to “follow” another user.

    +
  10. +
  11. +
      +
    1. In the message board, click Add People and add test-user-2 as a person that test-user-1 follows.
    2. +
    +
    + +
    +
  12. +
    1. +
    2. Log in as test-user-2 and post a message as this user to the message board.
    3. +
  13. +
  14. +
      +
    1. Go back and log in as user test-user-1.
    2. +
    +

    Because test-user-1 follows test-user-2, you should see the message sent by test-user-2 in the message board.

    +
    + +
    +
  15. +

17.

+

iOS SDK

+

If you want to write iOS applications that connect to App services, download the Apache Usergrid iOS SDK

+

Note: The Messagee iOS application uses RestKit, a popular REST framework for iOS, to communicate with App services. Because App services use a REST API, you can use any REST framework to talk with the service. However, the official App services iOS SDK provides a more convenient communication mechanism that you should use unless you’re already using RestKit or some other framework in your project.

+

Android client and SDK

+

Messagee is available as a sample Android app that acts as a App services client. The source for the Android version is packaged with the Apache Usergrid Android SDK in the /samples/messagee directory.

+

Download the Apache Usergrid Android SDK.

+

Javascript/HTML5 client and SDK

+

Messagee is also available as a sample HTML5 app that behaves in much the same way as the two previous examples. The source for the HTML5 version is packaged with the Apache Usergrid Javascript/HTML5 SDK in the /samples/messagee directory.

+

Download the Apache Usergrid Javascript/HTML5 SDK.

+
+
+
+
+
+
+
+ Questions? Please do ask on the mailing-list!
+ Found an error? We’d greatly appreciate a pull request about this article on github.
+
+
+
+ + + + + + + + + + + \ No newline at end of file