Repository: incubator-usergrid Updated Branches: refs/heads/ug2-doc-update 450a369d8 -> 3046c0a7a
Progress on User Management & Social Graph section Project: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/commit/be02dd0d Tree: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/tree/be02dd0d Diff: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/diff/be02dd0d Branch: refs/heads/ug2-doc-update Commit: be02dd0d78a73879281adbcc55d577a9be2d85f2 Parents: 450a369 Author: Dave Johnson <snoopd...@apache.org> Authored: Tue Aug 4 14:17:13 2015 -0400 Committer: Dave Johnson <snoopd...@apache.org> Committed: Tue Aug 4 14:17:13 2015 -0400 ---------------------------------------------------------------------- docs/index.rst | 17 +- docs/user-management/group.md | 0 docs/user-management/messagee-example.md | 1 + docs/user-management/tbd.md | 1 - docs/user-management/user-connections.md | 1 + docs/user-management/user-management.md | 42 ++++ docs/user-management/working-user-data.md | 278 +++++++++++++++++++++++++ 7 files changed, 333 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/index.rst ---------------------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 5512b71..331f96d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,7 +59,7 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: Security and Authentication + :caption: Security & Authentication security-and-auth/app-security security-and-auth/using-permissions @@ -75,9 +75,14 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: User Management and Social Graph + :caption: User Management & Social Graph - user-management/tbd + user-management/user-management + user-management/working-user-data + user-management/group + user-management/activity + user-management/user-connections + user-management/messagee-example .. _geolocation: @@ -91,7 +96,7 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: Assets and Files + :caption: Assets & Files asset-and-files/tbd @@ -99,7 +104,7 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: Counters and Events + :caption: Counters & Events counters-and-events/events-and-counters counters-and-events/creating-and-incrementing-counters @@ -109,7 +114,7 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: Organizations and Applications + :caption: Organizations & Applications orgs-and-apps/tbd http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/user-management/group.md ---------------------------------------------------------------------- diff --git a/docs/user-management/group.md b/docs/user-management/group.md new file mode 100644 index 0000000..e69de29 http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/user-management/messagee-example.md ---------------------------------------------------------------------- diff --git a/docs/user-management/messagee-example.md b/docs/user-management/messagee-example.md new file mode 100644 index 0000000..2817468 --- /dev/null +++ b/docs/user-management/messagee-example.md @@ -0,0 +1 @@ +# App Example - Messageea http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/user-management/tbd.md ---------------------------------------------------------------------- diff --git a/docs/user-management/tbd.md b/docs/user-management/tbd.md deleted file mode 100644 index 279d128..0000000 --- a/docs/user-management/tbd.md +++ /dev/null @@ -1 +0,0 @@ -# COMING SOON... \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/user-management/user-connections.md ---------------------------------------------------------------------- diff --git a/docs/user-management/user-connections.md b/docs/user-management/user-connections.md new file mode 100644 index 0000000..b2a15ef --- /dev/null +++ b/docs/user-management/user-connections.md @@ -0,0 +1 @@ +# Social Graph Connections http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/user-management/user-management.md ---------------------------------------------------------------------- diff --git a/docs/user-management/user-management.md b/docs/user-management/user-management.md new file mode 100644 index 0000000..6d1b363 --- /dev/null +++ b/docs/user-management/user-management.md @@ -0,0 +1,42 @@ +# User management & social graph +Whether you're developing apps for mobile or the Web, it's almost certain that you will need to be able to handle user management, as well as offer the types of social features users have come to expect from a rich app experience. Apigee's API BaaS makes all of this easy with default entity types and functionality available right out of the box. From user registration and profiles to login and authentication to activity feeds and social graph, you can create a social experience quickly and easily with just a few types of API calls. + +## User management +The default user entity in API BaaS is designed to model app users, meaning registering users and managing their profiles is as simple as sending and updating JSON via the API. Used in conjunction with our available social graph, as well as our OAuth 2.0 authentication and token authorization features, you have all the tools you need to manage your user base. + +Learn more about: + +* [User management](user-management.html) +* [Authentication & tokens](../security-and-auth/app-security.html) +* [Permissions and roles](../security-and-auth/using-permissions.html) + +## Group management +One of the most basic social features of any app is the ability to create groups of users to limit shared access to user or other app data. The default group entity in API BaaS was designed for this exact purpose. Associate a user with as many groups or sub-groups as you need, then apply permissions or roles to define shared access to API BaaS data. + +Learn more about: + +* [Group management](group.md) +* [Permissions and roles](../security-and-auth/using-permissions.html) + +## Social connections +To create a rich social graph, your app needs to be able to create connections between users. API BaaS makes this process lightweight by allowing you to create social connections and generic entity connections between users to model relationships by working with simple URI paths. + +For example, you could create a 'likes' relationship between two users with a POST: + + https://api.usergrid.com/your-org/your-app/users/Arthur/likes/users/Ford + +You could then retrieve all the users Arthur 'likes' with a GET to populate a list in your UI: + + https://api.usergrid.com/your-org/your-app/users/Arthur/likes + +Learn more about: + +* [Social connections](user-connections.html) +* [Generic entity connections](../data-storage/relationship.html) + +## Activity feeds +Activity feeds can be an essential way of establishing a social dimension of your user experience. Allow users to actively publish activities, such as status messages, or have your application code passively publish activities based on user actions, such as posting a photo. Activity feeds can be created and shared at both the user and group level, giving you the flexibility to present activity feeds that are most relevant to your users. + +Learn more about: + +* [Activity feeds] http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/be02dd0d/docs/user-management/working-user-data.md ---------------------------------------------------------------------- diff --git a/docs/user-management/working-user-data.md b/docs/user-management/working-user-data.md new file mode 100644 index 0000000..56dad3a --- /dev/null +++ b/docs/user-management/working-user-data.md @@ -0,0 +1,278 @@ +# Working with User Data +You can store and manage user data as User entities. With user data in your application, you can add support for a wide variety of features common to mobile apps. For example, you can: + +* Control access to data by defining permission rules. (See Security & token authentication for more.) +* Present content specific to each user, such as their list of favorites. +* Support social features, such as letting users "follow" one another, for example. + +In mobile applications, data about users is typically added by users themselves when they register through your app. The topics in this section provide specific cURL and SDK-specific examples for getting things done with user data. + +## Creating users + +A user entity represents an application user. Using API Services you can create, retrieve, update, delete, and query user entities. See User entity properties for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application. + +### Request Syntax + + curl -X POST "https://api.usergrid.com/your-org/your-app/users"; -d '{ "username": "john.doe", "email": "john....@gmail.com", "name": "John Doe", "password": "test1234" }' + +Use the POST method to create a new user in the users collection. + +### Request URI + + POST /<org_id>/<app_id>/users + +Parameters + +Parameter Description +--------- ----------- +uuid | org_id Organization UUID or organization name. +uuid | app_id Application UUID or application name. +request body One or more sets of user properties. + +The username is mandatory and must be unique. Here's an example: + + { + "username" : "john.doe", + "email" : "john....@gmail.com", + "name" : "John Doe", + "password" : "test1234" + } + +Although the password parameter is not mandatory, if you don't specify it, the user will not be able to log in using username and password credentials. If a password is not specified for the user, and you're an Admin, you can set a password for the user (see Setting a password). + +__ Note__: The username can contain any combination of characters, including those that represent letters, numbers, and symbols. + +### Example + +__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. + +### Request + + curl -X POST "https://api.usergrid.com/my-org/my-app/users"; -d '{"username":"john.doe","email":"john....@gmail.com","name":"John Doe"}' + +### Response + + { + "action" : "post", + "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20", + "params" : { }, + "path" : "/users", + "uri" : "https://api.usergrid.com/steventraut/mynewapp/users";, + "entities" : [ { + "uuid" : "8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc", + "type" : "user", + "name" : "John Doe", + "created" : 1390533228622, + "modified" : 1390533228622, + "username" : "john.doe", + "email" : "john....@gmail.com", + "activated" : true, + "picture" : "http://www.gravatar.com/avatar/e13743a7f1db7f4246badd6fd6ff54ff";, + "metadata" : { + "path" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc", + "sets" : { + "rolenames" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/roles", + "permissions" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/permissions" + }, + "collections" : { + "activities" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/activities", + "devices" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/devices", + "feed" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/feed", + "groups" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/groups", + "roles" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/roles", + "following" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/following", + "followers" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/followers" + } + } + }], + "timestamp" : 1390533228619, + "duration" : 142, + "organization" : "my-org", + "applicationName" : "my-app" + } + + +## Retrieving user data + +You can retrieve data about users through cURL or one of the SDKs. Each provides a way to filter the list of users by data associated with the user, such as username or UUID, or other properties in the user entity. + +See User entity properties for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application. + +### Request Syntax + + curl -X GET "https://api.usergrid.com/your-org/your-app/users"; + +Use the GET method to retrieve user data. + +### Request URI + + GET /<org_id>/<app_id>/users/<uuid | username | email_address | ?ql=query_string> + +Parameters + +Parameter Description +--------- ----------- +uuid | org_id Organization UUID or organization name +uuid | app_id Application UUID or application name +user identifier User UUID, username, or email address. + +The alias ``/users/me`` can be used in place of the current userâs uuid, username, or email address. Note: The ``/users/me`` endpoint is accessible only if you provide an access token with the request (see Authenticating users and application clients). If you make an anonymous ("guest") call, the system will not be able to determine which user to return as /users/me. + +__Note__: The username can contain any combination of characters, including those that represent letters, numbers, and symbols. + +### Example + +__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](../security-and-auth/authenticating-users-and-application-clients.html) for details. + +Requests + + # Get a user by username. + curl -X GET "https://api.usergrid.com/my-org/my-app/users/jane.doe"; + + # Get a user by UUID. + curl -X GET "https://api.usergrid.com/my-org/my-app/users/a407b1e7-58e8-11e1-ac46-22000a1c5a67e"; + + # Get a user by email. + curl -X GET "https://api.usergrid.com/my-org/my-app/users/jane....@gmail.com"; + + # Get user data filtering by their city property value. + curl -X GET "https://api.usergrid.com/my-org/my-app/users?ql=select%20*%20where%20adr.city%3D'Chicago'" + +Response + + { + "action" : "get", + "application" : "1c8f60e4-da67-11e0-b93d-12313f0204bb8", + "params" : { + "_": [ + "1315524419746" + ] + }, + "path" : "https://api.usergrid.com/12313f0204bb-1c8f60e4-da67-11e0-b93d/1c8f60e4-da67-11e0-b93d-12313f0204bb/users";, + "uri" : "https://api.usergrid.com/005056c00008-4353136f-e978-11e0-8264/4353136f-e978-11e0-8264-005056c00008/users";, + "entities" : [ { + "uuid" : "78c54a82-da71-11e0-b93d-12313f0204b", + "type" : "user", + "created" : 1315524171347008, + "modified" : 1315524171347008, + "activated" : true, + "email" : "jane....@gmail.com", + "metadata" : { + "path" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb", + "sets" : { + "rolenames" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/rolenames", + "permissions" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/permissions" + }, + "collections" : { + "activities" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/activities", + "devices" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/devices", + "feed" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/feed", + "groups" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/groups", + "roles" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/roles", + "following" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/following", + "followers" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/followers" + } + }, + "username" : "jane.doe" + } + ... Additional entities here if data for multiple users was returned... + ], + "timestamp" : 1315524421071, + "duration" : 107, + "organization" : "my-org", + "applicationName": "my-app" + } + +## Updating & deleting user data + +To update or delete a user, perform an update or delete on the associated user entity as you would any other entity. For more information and code samples, see [Updating Data Entities](../data-storage/entities.html#updating-data-entities) and [Deleting Data Entities](../data-storage/entities.html#deleting-data-entities). + +## Changing a user password + +Changing a user's password + +### Request syntax + + curl -X PUT https://api.usergrid.com/<org>/<app>/users/<username_or_email>/password -d '{oldpassword:<old_password>,newpassword:<new_password>}' + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +username_or_email Username or email of the user entity whose password you want to reset. +old_password User entity's old password. +new_password User entity's new password. + +__Note__: If your request is authenticated with an application-level token, then ``old_password`` is not required. For more, see [Application client authentication](../security-and-auth/authenticating-users-and-application-clients.html#application-client-authentication). + +Example request + + curl -X PUT https://api.usergrid.com/my-org/my-app/users/john.doe/password -d '{"newpassword":"foo9876a","oldpassword":"bar1234b"}' + +Example response + + { + "action": "set user password", + "timestamp": 1355185897894, + "duration": 47 + } + +## Resetting a user password + +Resetting a user's password + +Usergrid provides a standard password reset flow that can be implemented to allow a user to reset their password without having to provide their old password. The most common use of this would be a 'Forgot password?' feature in your app. + +Note that you can also implement your own password reset flow using application-level authentication and the /password endpoint. For more, see [Changing a user password](#changing-a-user-password). + +To use the API BaaS password reset flow, do the following: + +### STEP 1: Get the password reset request form. + +Make a GET request to the following: + + /users/<username>/resetpw + +For example, using cURL, a request to reset the password for a user with username 'someUser' would look like this: + + curl -x GET https://api.usergrid.com/your-org/your-app/users/someUser/resetpw + +### STEP 2: Display the returned password reset request form to the user. + +The request to ``/resetpw`` will return the HTML for the standard Usergrid password reset request form that you will display to your user. The request form requires the users to provide their username as well as answer a standard CAPTCHA challenge: + + <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> + <html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Reset Password</title> + <link rel="stylesheet" type="text/css" href="/css/styles.css" /> + </head> + <body> + <div class="dialog-area"> + + <form class="dialog-form" action="" method="post"> + <fieldset> + <p> + Enter the captcha to have your password reset instructions sent to + someu...@adomain.com + </p> + <p id="human-proof"></p> + <script type="text/javascript" src="https://www.google.com/recaptcha/api/challenge?k=6LdSTNESAAAAAKHdVglHmMu86_EoYxsJjqQD1IpZ";></script> + + <p class="buttons"> + <input type="submit" value="submit" /> + </p> + </fieldset> + </form> + </div> + </body> + </html> + +You can apply any additional styling you wish to the form to make it match the style of your app before displaying it to the user. + +### STEP 3: Let Usergrid handle the rest! + +Once the user submits the form with their username, they will receive an email from Usergrid that contains a link to the password reset form, where they can specify a new password. The user entity will be updated immediately.
