http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/entity-connections/relationships.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/entity-connections/relationships.txt b/content/docs/_sources/entity-connections/relationships.txt new file mode 100644 index 0000000..73bc6c3 --- /dev/null +++ b/content/docs/_sources/entity-connections/relationships.txt @@ -0,0 +1,98 @@ +# Relationships + +## Creating connections between entities + +One of the most useful features of Usergrid is the ability to create +connections between entities. A simple example of this is the +Twitter-like use of *following*, where one user forms a connection with +another by subscribing to any tweets they post. [Messagee +Example](/messagee-example) walks you through an example of following +other users in our sample app, *Messagee*. Here is the basic format: + + POST https://api.usergrid.com/my-org/my-app/users/fred/following/users/barney + +This API call results in two users, Fred and Barney, linked with a +connection where Fred is following Barney. + +If you create a *following* connection between two users, Apache Usergrid +automatically creates a virtual connection called *followers* that +mirrors the *following* connection. In other words, if you create a +connection where Fred is following Barney, Apache Usergrid automatically +creates a virtual connection where Fred is a follower of Barney. + +Note that there is no mirror connection established. Apache Usergrid only +creates a mirror connection when you create a *following* connection. It +does not create a mirror connection for other verbs such as likes. + +You can see all the users that Fred is following, in this case only +Barney, by making the following API call: + + GET https://api.usergrid.com/my-org/my-app/users/fred/following + +You can see all of barneyâs followers, in this case only Fred, by making +the following API call: + + GET https://api.usergrid.com/my-org/my-app/users/barney/followers + +The *followers* connection is a virtual connection because you canât use +it to link two entities. In other words, you canât make fred a follower +of barney by using a *followers* connection. Â **This is wrong:** + + POST https://api.usergrid.com/my-org/my-app/users/barney/followers/users/fred + +To create a *following* connection with the users switched, so that +Barney is following Fred, do this: + + POST https://api.usergrid.com/my-org/my-app/users/barney/following/users/fred + +You can now see Fredâs followers (only Barney) by making the following +call: + + GET https://api.usergrid.com/my-org/my-app/users/fred/followers + +## Creating other connections + +You can extend this connection structure to create connections using any +"verb" that can link two entities. For example, you could use likes to +denote a connection between a user and his dog. First, create a dogs +collection: + + POST https://api.usergrid.com/my-org/my-app/dogs + +Then populate this collection with a new dog named Dino: + + POST https://api.usergrid.com/my-org/my-app/dogs {"name" : "dino"} + +Then create a likes connection between Fred and his dog Dino: + + POST https://api.usergrid.com/my-org/my-app/users/fred/likes/dogs/dino + +Getting connections +------------------- + +### Get all connections for an entity + +To get a list that only contains the connections, do a GET on the +connections sub-property of the entity: + + GET https://api.usergrid.com/my-org/my-app/users/fred/connections + +### Get information on a specific connection type + +To get a list of users who like Fred: + + GET https://api.usergrid.com/my-org/my-app/users/fred/connecting/likes + +To get a list of all dogs that Fred likes: + + GET https://api.usergrid.com/my-org/my-app/users/fred/likes/dog + +Deleting a connection +--------------------- + +You can delete a connection in a way similar to creating one. Just +replace the POST method with the DELETE method. For example, you can +delete the connection between fred and barney with the following API +call: + + DELETE https://api.usergrid.com/my-org/my-app/users/fred/following/barney
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/entity-connections/retrieving-entities.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/entity-connections/retrieving-entities.txt b/content/docs/_sources/entity-connections/retrieving-entities.txt new file mode 100644 index 0000000..31eaf9c --- /dev/null +++ b/content/docs/_sources/entity-connections/retrieving-entities.txt @@ -0,0 +1,94 @@ +# Retrieving connections + +Viewing all of an entities connections +To see all of the connection types associated with an entity, simply retrieve the entity. + +All of the connection types the entity has made to other entities will appear in the metadata.connections property. + +All of the connection types that other entities have made to the entity will appear in the metadata.connecting property. + +For user entities, following/followers connections can be accessed by sending a GET request to the URL in the collections.following and collections.followers properties. + +Retrieve connected entities by connection type +To get a list of entities a specified entity has connected to with a specific connection type, do the following: + +## Request syntax + + curl -X GET https://api.usergrid.com/<org>/<app>/<collection>/<entity>/<relationship> + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +collection Name or UUID of the collection of the entity you want to retrieve the connections of. +entity Name or UUID of the entity whose connections you want to retrieve +relationship The connection type you want to retrieve the entities for. + +For example, specifying a relationship of 'likes' would return a list of all entities that have the 'likes' connection with the specified entity. + +Example request + + curl -X GET https://api.usergrid.com/your-org/your-app/users/Arthur/likes + +Example response + +Notice that the entities are returned as a JSON array in the entities property. + + { + "action" : "get", + "application" : "dk88fh4r-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes", + "uri" : "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes";, + "entities" : [ { + "uuid" : "5bcc47ca-cfed-11e3-8bde-a7e008061e10", + "type" : "user", + "created" : 1398810410556, + "modified" : 1398810410556, + "username" : "Ford", + "activated" : true, + "metadata" : { + "connecting" : { + "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/connecting/likes" + }, + "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10", + "sets" : { + "rolenames" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles", + "permissions" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/permissions" + }, + "collections" : { + "activities" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/activities", + "devices" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/devices", + "feed" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/feed", + "groups" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/groups", + "roles" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles", + "following" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/following", + "followers" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/followers" + } + } + } ], + "timestamp" : 1398884631067, + "duration" : 41, + "organization" : "your-org", + "applicationName" : "your-app" + } + +## Retrieve all connected entities + +To get a list of all the entities a specified entity has connected to, use the same method as shown above in Retrieve connected entities by connection type, and set the relationship to connections. + +All of the entities that have made a connection of that type to the specified entity will be returned in the entities property of the response. + +## Retrieve all connecting entities by type + +To get a list of all the entities that have created a connection of a specific type to a specified entity, use the same method as shown above in Retrieve connected entities by connection type, and set the relationship to connecting/<relationship>. + +All of the entities that have made a connection to the specified entity will be returned in the entities property of the response. + +## Retrieve all connecting entities + +To get a list of all the entities that have connected to a specified entity, use the same method as shown above in Retrieve connected entities by connection type, and set the relationship to connecting. + +All of the entities that have made a connection to the specified entity will be returned in the entities property of the response. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/geolocation/geolocation.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/geolocation/geolocation.txt b/content/docs/_sources/geolocation/geolocation.txt new file mode 100644 index 0000000..ede4e3c --- /dev/null +++ b/content/docs/_sources/geolocation/geolocation.txt @@ -0,0 +1,72 @@ +# Geolocating your Entities +Many of today's apps are enhanced by the use of geolocation â wireless detection of the physical location of a remote device. These apps determine the user's position and use this data to enhance user experience. For example, apps can capture the exact location where a picture was taken or determine what businesses stored in the database to return to the user based on their current location. + +API Services provides a standard format for storing geolocation information in any entity, as well as syntax for querying that data based on distance from a latitude/longitude point. + +## Saving location data in an entity +In API Services, geolocation data is saved in the location property of an entity with latitude and longitude sub-properites in the following format: + + "location": { + "latitude": <latitude_coordinate>, + "longitude": <longitude_coordinate> + } + +An entity's geolocation can be specified when the entity is [created](../data-storage/entities.html#creating-custom-data-entities) or added later by [updating](../data-storage/entities.html#updating-data-entities) an existing entity. + +For example, the following entity describes a restaurant: + + { + "uuid" : "03ae956a-249f-11e3-9f80-d16344f5a0e1", + "type" : "restaurant", + "name" : "Rockadero", + "location": { + "latitude": 37.779632, + "longitude": -122.395131 + } + "created" : 1379975113142, + "modified" : 1379975113142, + "metadata" : { + "path" : "/restaurants/03ae956a-249f-11e3-9f80-d16344f5a0e1" + } + +## Querying location data +Location-aware apps require the ability to return content and results based on the user's current location. To easily enable this, API Services supports the following query parameter to retrieve entities within a specified distance of any geocoordinate based on its location property: + + location within <distance_in_meters> of <latitude>, <longitude> + +The returned results are sorted from nearest to furthest. Entities with the same location are returned in the order they were created. + +The location parameter can be appended to any standard API Services query. For more information on how to query your API Services data, see Querying your data. + +For example, here is how you would find all the devices within 8,046 meters (~10 miles) of the center of San Francisco: + + curl -X GET https://api.usergrid.com/your-org/your-app/devices?ql=location within 8046 of 37.774989,-122.419413 + +## Enrich your app with location data +Location-awareness has become a feature users expect in many types of mobile applications because of its ability to create a more personalized and relevant experience for each user. With this in mind, the geolocation feature in API Services was designed to work with many of the available [default data entities](../api-docs.html#models) to allow app developers to easily integrate powerful in-app features that can increase user engagement. + +Here are just a few of the ways that saving location data to a data entity can improve an app: + +<table class="usergrid-table"> +<tr> + <th>Entity</th> + <th>Usage</th> +</tr> +<tr> + <td>user</td> + <td>Save the location of a user's home as part of their profile in the ``users`` collection to suggest upcoming special events or activities located nearby, or to display advertisements that are relevant based on the user's proximity to a business.</td> +</tr> +<tr> + <td>device</td> + <td>Periodically save the location data returned from a user's device, then query the ``devices`` collection to send offers and alerts to user's that are located near your business with a [push notification](../push-notifications/push-notifications-overview).</td> +</tr> +<tr> + <td>activity</td> + <td>Create stronger social connections by associating a user ``activity`` with the location where it occurred. The activity can then be displayed to nearby friends and family, or used to enrich the user's activity stream.</td> +</tr> +<tr> + <td>asset</td> + <td>Save user photos with location data in the ``asset collection`` to allow users to retrieve and sort their memories based on when and where they happened.</td> +</tr> +</table> + http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/geolocation/tbd.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/geolocation/tbd.txt b/content/docs/_sources/geolocation/tbd.txt new file mode 100644 index 0000000..279d128 --- /dev/null +++ b/content/docs/_sources/geolocation/tbd.txt @@ -0,0 +1 @@ +# COMING SOON... \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/getting-started/creating-a-new-application.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/getting-started/creating-a-new-application.txt b/content/docs/_sources/getting-started/creating-a-new-application.txt new file mode 100644 index 0000000..cc5f577 --- /dev/null +++ b/content/docs/_sources/getting-started/creating-a-new-application.txt @@ -0,0 +1,14 @@ +# Creating a new application + +## Creating an application +You can use the admin portal to create applications. An application represents the data associated with your app. Through an application, you handle the entities associated with your app, including users, devices, events, and so on. + +To create a new application with the admin portal: + +1. In the admin portal, from the dropdown menu at the far top left, select the organization to which you will add the new application. +1. Click the ADD NEW APP button, located at the top of the screen, next to the application drop-down. +1. In the dialog box, enter a new application name, then click the Create button. Your new application will automatically be selected in the applications drop-down menu. +Applications can also be created programmatically with a POST request to the API. For more, see Application. + +## Securing an application +If this is going to be a production application, be sure to configure security roles that provide only the level of access your users will need. For more on security, see Security best practices. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/getting-started/creating-account.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/getting-started/creating-account.txt b/content/docs/_sources/getting-started/creating-account.txt new file mode 100644 index 0000000..1440926 --- /dev/null +++ b/content/docs/_sources/getting-started/creating-account.txt @@ -0,0 +1,21 @@ +# Creating an Usergrid Account +To get started using the Usergrid, you'll need an Usergrid account. (Before reading this, you should already be familiar with what Usergrid can do to support your apps. If you're still curious about that, you might want to read Usergrid features first.) + +With an account, you get the following useful things: + +* A sandbox application you can try things with (we automatically create one for you with your new account). The sandbox is a partitioned area of the data store where you can add example data and try out API calls. The sandbox isn't secure, but it's handy to play in. For more about the sandbox, see "Using Your Application Sandbox". +* The ability to create more applications (in addition to the sandbox). You can (and should!) make these as secure as you need to. These are the applications that you'll have behind the apps you make available to your users. +* Access to the Admin Portal. In the portal, you can do the following: +** Create and manage applications. +** Manage your app's users, including access levels. +** Manage the data in your app. +** Manage app features, including push notifications, activities, analytics, and so on. +** Try out API calls with a shell command window. +** To create an Usergrid account and see a very short tutorial to get started with, go to the get started page. + +## Next steps +Ready to learn and do more? + +* Install an SDK that will be most useful for your application environment. For more about Usergrid's SDKs, see SDKs. +* Review Usergrid features for information on concepts and features. +* Consult the API Reference for usage details. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/getting-started/using-a-sandbox-app.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/getting-started/using-a-sandbox-app.txt b/content/docs/_sources/getting-started/using-a-sandbox-app.txt new file mode 100644 index 0000000..7fb9cd1 --- /dev/null +++ b/content/docs/_sources/getting-started/using-a-sandbox-app.txt @@ -0,0 +1,39 @@ +# Using a Sandbox Application + +## What is the sandbox application? + +When you create a new Usergrid account (see Creating an Usergrid Account) to use services for developers, Usergrid creates a new application for you on its servers. With the new application, called "sandbox," you can add your own example data and try out API calls that do things with the data. Be sure to see Using the API for suggestions. + +## Is the sandbox secure? + +To keep things simple and make it easier for you to try things out, the sandbox application has all authentication disabled. That way, it doesnât require an access token for application-level calls to the API. Permissions are so open on the sandbox application because its "guest" role offers full permissions for all access paths -- that is, GET, POST, PUT, and DELETE for /**. Learn more about roles and permissions in Managing access by defining permission rules. + +<!-- workaround a Sphinx bug --> +<div class="admonition warning"><p class="first admonition-title">Warning</p><p class="last"> +<p class="last">Never use a sandbox app for production. +Keep in mind that the lack of authentication means that a sandbox application is not secure enough for important or sensitive data. A sandbox is just for experimentation while you learn how the services work, and should never be used for a production application. As with other Usergrid applications you create, a sandbox application is an area of the data store where you can put your own data. You can create as many other applications as you like, including more sandbox applications. When it comes to production (secured) applications, a good rule of thumb is to create one application for each mobile app you develop. +</p> +</div> + +## Creating a New Sandbox Application + +You may want to create (or re-create) a sandbox application. For example, you may want to create a sandbox application for another organization or you may want to create another application for testing purposes. + +<!-- workaround a Sphinx bug --> +<div class="admonition warning"><p class="first admonition-title">Warning</p><p class="last"> +Guest Role should never be given full permissions. +Giving the guest role full permissions should be used only for testing and should not be used in production. Before you make your app âliveâ, you should remove the guest permissions for /**. +</p></div> + +Use the following steps to create a sandbox app: + +1. Create a new application using the admin portal. You can name the application whatever you like (including "sandbox"). +2. Set full access permissions for the guest role, as follows: + 1. In the admin portal, click Users, then click Roles. + 2. On the Roles page, in the list of roles, click Guest. + 3. For the Guest role, under Permissions, click Add Permission. + 4. In the New Permission dialog, enter the following in the Path box: ``/**`` + 5. Select the following check boxes: get, post, put, and delete. + 6. Click the Add button. + 7. If there are other permissions listed, delete them. + http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/getting-started/using-the-api.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/getting-started/using-the-api.txt b/content/docs/_sources/getting-started/using-the-api.txt new file mode 100644 index 0000000..9a7ba2d --- /dev/null +++ b/content/docs/_sources/getting-started/using-the-api.txt @@ -0,0 +1,150 @@ +# Using the API +Usergrid uses a pure REST (Representational State Transfer) API built as a collection of resources. Resource locations are described by paths that are related intrinsically to collections and entities in collections. + +This section gives several examples of how to construct API requests. To focus on what's important, the examples use an abbreviated path that starts after the application UUID, or application name. For example, instead of giving a fully qualified path name as in: + + https://api.usergrid.com/your-org/your-app/users + +the example simply lists this: + + /users + +## Supported HTTP methods +When building a REST API, the challenge is to represent the data and the action upon the data as a path to a resource that can be created, retrieved, updated, or deleted. The HTTP methods POST, GET, PUT, and DELETE correspond to the actions that are applied to resources. + +## Base URL +The base url for all requests made to Usergrid depends on where you have Usergrid installed. If you are using Apigee's trial Usergrid service, the base URL is ``https://api.usergrid.com.`` + +## Request construction +Usergrid interprets the URL resource path as a list of names, UUIDs, or queries. The basic path format is: + + https://api.usergrid.com/<org-uuid|org-name>/<app-uuid|app-name>/<collection-name>/<entity-uuid|entity-name> + +Note: You cannot mix UUIDs and names in the URL resource path. For example, the following is incorrect: + + https://api.usergrid.com/your-org/62de5d97-d28c-11e1-8d5c-12313b01d5c1/users/john.doe + +## Accessing collections +To access all entities in a collection, specify the path as follows: + + /users + +Such a request retrieves the first 10 entities in the collection /users sorted by their entity UUID. + +## Accessing entities +To access an entity in a collection, specify the path as follows: + + /<collection>/<uuid|name> + +where ``<collection>`` is the collection name, and <uuid|name> is the entityâs uuid or name. + +To access a user in the users collection, specify the path as follows: + + /users/<uuid|username|email_address> + +where ``<uuid|username|email_address>`` is the userâs uuid, username, or email address. + +For example, the following request retrieves the entity named dino from the dogs collection: + + /dogs/dino + +## Issuing queries +You can issue a query in an API request that retrieves items from a collection. Here is the typical format for queries: + + /<collection>?ql=<query> + +where <query> is a query in the query language. + +For example, this request retrieves users whose Facebook first name is john: + + /users?ql=select * where facebook.first_name ='john' + +For further information about queries, see Queries and parameters. + +## Authentication (OAuth) +Usergrid implements the OAuth 2.0 standard for authenticating users, clients and API requests. + +Generally, you will generate a token for every user of your app by providing the user's username and password. The token can then be sent with all API requests to ensure each user is only able to access and modify the resources you have granted them rights to. + +Note that by default access tokens are not needed to make requests to the default sandbox application in an organization. + +For more information on generating and using access tokens, see Authenticating users and application clients and Authenticating API requests. + +## Response format +All API methods return a response object that typically contains an array of entities: + + { + "entities" : [ + ... + ] + } + +Not everything can be included inside the entity, and some of the data that gets associated with specific entities isn't part of their persistent representation. This is metadata, and it can be part of the response as well as associated with a specific entity. Metadata is just an arbitrary key/value JSON structure. + +For example: + + { + "entities" : { + { + "name" : "ed", + "metadata" : { + "collections" : ["activities", "groups", "followers"] + } + } + }, + "metadata" : { + "foo" : ["bar", "baz"] + } + } + +For example, here is the response to a basic GET for a user entity: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/users", + "uri" : "https://api.usergrid.com/your-org/your-app/users";, + "entities" : [ { + "uuid" : "503f17da-ec39-11e3-a0dd-a554b7fbd57a", + "type" : "user", + "created" : 1401921665485, + "modified" : 1401921665485, + "username" : "someUser", + "email" : "someu...@yourdomain.com", + "activated" : true, + "picture" : "http://www.gravatar.com/avatar/dc5d478e9c029853fbd025bed0dc51f8";, + "metadata" : { + "path" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a", + "sets" : { + "rolenames" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles", + "permissions" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/permissions" + }, + "collections" : { + "activities" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/activities", + "devices" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/devices", + "feed" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/feed", + "groups" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/groups", + "roles" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles", + "following" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/following", + "followers" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/followers" + } + } + } ], + "timestamp" : 1401921673597, + "duration" : 12, + "organization" : "your-org", + "applicationName" : "your-app" + } + +## SDKs +To make the integration of Usergrid features into your application code quicker and easier, Usegrid offers SDKs in a variety of languages. The SDKs contain language-specific methods that allow you to issue API requests from your application code in your preferred language. SDKs are available for the following languages: + +* iOS +* Android +* JavaScript/HTML5 +* Node.js +* Ruby +* .NET + +For more information, see SDKs. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/index.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/index.txt b/content/docs/_sources/index.txt new file mode 100644 index 0000000..e25eebc --- /dev/null +++ b/content/docs/_sources/index.txt @@ -0,0 +1,160 @@ +***************************** +Apache Usergrid Documentation +***************************** + +.. _intro:: + +.. toctree:: + :maxdepth: 2 + :caption: Introduction + + introduction/usergrid-features + introduction/data-model + introduction/async-vs-sync + +.. _getting-started: + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + getting-started/creating-a-new-application + getting-started/creating-account + getting-started/using-a-sandbox-app + getting-started/using-the-api.md + +.. _data-storage: + +.. toctree:: + :maxdepth: 2 + :caption: Data Storage + + data-storage/data-store-dbms + data-storage/optimizing-access + data-storage/collections + data-storage/entities + +.. _data-queries: + +.. toctree:: + :maxdepth: 2 + :caption: Data Queries + + data-queries/querying-your-data + data-queries/query-parameters + data-queries/operators-and-types + data-queries/advanced-query-usage + +.. _entity-connections: + +.. toctree:: + :maxdepth: 2 + :caption: Entity Connections + + entity-connections/connecting-entities + entity-connections/retrieving-entities + entity-connections/disconnecting-entities + +.. _security-and-authentication: + +.. toctree:: + :maxdepth: 2 + :caption: Security & Authentication + + security-and-auth/app-security + security-and-auth/using-permissions + security-and-auth/authenticating-users-and-application-clients + security-and-auth/user-authentication-types + security-and-auth/changing-token-time-live-ttl + security-and-auth/authenticating-api-requests + security-and-auth/revoking-tokens-logout + security-and-auth/facebook-sign + security-and-auth/securing-your-app + +.. _user-management-and-social-graph: + +.. toctree:: + :maxdepth: 2 + :caption: User Management & Social Graph + + user-management/user-management + user-management/working-user-data + user-management/group + user-management/activity + user-management/user-connections + user-management/messagee-example + +.. _geolocation: + +.. toctree:: + :maxdepth: 2 + :caption: Geo-location + + geolocation/geolocation + +.. _asset-and-file-management: + +.. toctree:: + :maxdepth: 2 + :caption: Assets & Files + + asset-and-files/uploading-assets.md + asset-and-files/retrieving-assets.md + asset-and-files/folders.md + +.. _counters-and-events: + +.. toctree:: + :maxdepth: 2 + :caption: Counters & Events + + counters-and-events/events-and-counters + counters-and-events/creating-and-incrementing-counters + counters-and-events/retrieving-counters + +.. _organization-and-application-management: + +.. toctree:: + :maxdepth: 2 + :caption: Organizations & Applications + + orgs-and-apps/managing + orgs-and-apps/organization + orgs-and-apps/application + orgs-and-apps/adminuser + +.. _rest-endpoints: + +.. toctree:: + :maxdepth: 0 + :caption: API Reference + + rest-endpoints/api-docs + +.. _sdks: + +.. toctree:: + :maxdepth: 2 + :caption: Client SDKs + + sdks/tbd + +.. _installation: + +.. toctree:: + :maxdepth: 2 + :caption: Installing the Stack + + installation/ug1-deploy-to-tomcat + installation/ug1-launcher-quick-start + installation/ug2-deploy-to-tomcat + +.. _about: + +.. toctree:: + :maxdepth: 2 + :caption: More about Usergrid + + reference/presos-and-videos + reference/contribute-code + http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/installation/ug1-deploy-to-tomcat.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/installation/ug1-deploy-to-tomcat.txt b/content/docs/_sources/installation/ug1-deploy-to-tomcat.txt new file mode 100644 index 0000000..5356a94 --- /dev/null +++ b/content/docs/_sources/installation/ug1-deploy-to-tomcat.txt @@ -0,0 +1,179 @@ +# Usegrid 1: Deploying to Tomcat + +This is a guide that explains how to install and run Usergrid using stock Tomcat and Cassandra on a single computer. + +NOTE: running Cassandra on a single computer is something you should do ONLY for testing purposes. You don't want to run one node in production even just to start out. To get the benefit of Cassandra's architecture, which is designed to support linear scalability. You should be running a Cassandra cluster with at least three nodes. + +For more information: + +* [Cassandra FAQ: Can I Start With a Single Node?](http://planetcassandra.org/blog/post/cassandra-faq-can-i-start-with-a-single-node/) +* [Why don't you start off with a âsingle & smallâ Cassandra server](http://stackoverflow.com/questions/18462530/why-dont-you-start-off-with-a-single-small-cassandra-server-as-you-usually) + +## Requirements + +* [JDK 1.7](http://www.oracle.com/technetwork/java/javase/downloads/index.html) +* [Maven](http://maven.apache.org/) + +## Download + +Use GitHub to clone the [apache/incubator-usergrid](https://github.com/apache/incubator-usergrid) repo. + +Or you can start by [downloading our latest code](https://github.com/apache/incubator-usergrid/archive/master.zip) and extract it. + +## Building + +From the command line, navigate to `stack` directory and type the following: + + mvn clean package -DskipTests=true + +Once you are done the Usergrid application will be package as a Java EE WAR file at the location __stack/rest/target/ROOT.war__. + +Install and configure Cassandra +--- + +Install Cassandra, don't edit configuration files as we just want default values for this simple setup. Here are the [instructions for installing Cassandra](http://wiki.apache.org/cassandra/GettingStarted) + +Install and configure Tomcat +--- + +Follow instructions, don't edit configuration files as we just want default values for this simple setup. Here are the [instructions for installing Tomcat 7](http://tomcat.apache.org/tomcat-7.0-doc/setup.html) + +Add Usergrid WAR to Tomcat +--- + +Remove the existing `tomcat/webapps/ROOT` directory. + +Place the Usergrid `ROOT.war` file into the `tomcat/webapps` directory + +Add Usergrid configuration file to Tomcat +--- + +Create a ____usergrid-custom.properties____ file and place it in Tomcat's __lib__ directory. You can find an example properties file below that should work well for a local Tomcat & Cassandra setup. You will probably only need to change the properties below to use your email address and preferred password for the install. + + + usergrid.sysadmin.login.allowed=true + usergrid.sysadmin.login.name=superuser + usergrid.sysadmin.login.password=pw123 + usergrid.sysadmin.email=m...@example.com + usergrid.sysadmin.login.email=mys...@example.com + usergrid.management.mailer=Myself<mys...@example.com> + usergrid.test-account.admin-user.email=mys...@example.com + usergrid.test-account.admin-user.password=test + +Run Usergrid Database & Super User Setup +--- + +Start Tomcat and use your web browser to visit the URLs below. While you do this you might want to watch the logs under tomcat/logs for clues, just in case anything goes wrong. + +Database setup URL - [http://localhost:8080/system/database/setup](http://localhost:8080/system/database/setup) + +When prompted to login use the sysadmin credentials that you specified in your __usergrid-custom.properties__ file. Based on the example above that would be superuser and pw123. If the operation is successful you should a message like the one below in your browser. If not, check your logs for clues about what went wrong. + + { + "action" : "cassandra setup", + "status" : "ok", + "timestamp" : 1379424622947, + "duration" : 76 + } + +Superuser setup URL - [http://localhost:8080/system/superuser/setup](http://localhost:8080/system/superuser/setup) + +You should not be prompted for login because you already logged into for the Database Setup. If setup works, you should see a message like this: + + { + "action" : "superuser setup", + "status" : "ok", + "timestamp" : 1379424667936, + "duration" : 2 + } + +Build the Usergrid Console +--- +The Usergrid Console is an admin interface written in JavaScript that connects to your running Usergrid instance. For evaluation purposes, you can run it within Tomcat. Build it by following the steps [here](https://github.com/apache/incubator-usergrid/blob/master/portal/README.md). Once built, copy the directory _portal/build/usergrid-portal_ to _tomcat/webapps_. + + +Login to the Usergrid Console & get started +--- +You should now be able to login to the Usergrid console and start configuring applications, users and more. + +You can use an static version of the portal to get started: + +http://localhost:8080/usergrid-portal/(http://localhost:8080/usergrid-portal) + + +Example __usergrid-custom.properties__ file +--- +Here's a complete example properties file to get you started. + + # Minimal Usergrid configuration properties for local Tomcat and Cassandra + # + # The cassandra configuration options. + + # The cassandra host to use + cassandra.url=localhost:9160 + + # if your cassandra instance requires username/password + cassandra.username=someuser + cassandra.password=somepassword + + # The strategy to use when creating the keyspace. This is the default. + # We recommend creating the keyspace with this default, then editing it + # via the cassandra CLI to meet the client's needs. + cassandra.keyspace.strategy=org.apache.cassandra.locator.SimpleStrategy + + # The default replication factor for the simple strategy. Again, leave the + # default, create the app, then use the cassandra cli to set the replication + # factor options. This can become complicated with different topologies and + # is more a Cassandra administration issue than a UG issue. + cassandra.keyspace.strategy.options.replication_factor=1 + + ###################################################### + # Custom mail transport. Not usually used for local testing + + #mail.transport.protocol=smtps + #mail.smtps.host=email-smtp.us-east-1.amazonaws.com + #mail.smtps.port=465 + #mail.smtps.auth=true + #mail.smtps.quitwait=false + #mail.smtps.username= + #mail.smtps.password= + + ###################################################### + # Admin and test user setup (change these to be their super user + + usergrid.sysadmin.login.name=superuser + usergrid.sysadmin.login.email=mys...@example.com <--- Change this + usergrid.sysadmin.login.password=pw123 <--- Change this + usergrid.sysadmin.login.allowed=true + usergrid.sysadmin.email=mys...@example.com <--- Change this + + # Enable or disable this to require superadmin approval of users + usergrid.sysadmin.approve.users=false + + ###################################################### + # Auto-confirm and sign-up notifications settings + + usergrid.management.admin_users_require_confirmation=false + usergrid.management.admin_users_require_activation=false + usergrid.management.organizations_require_activation=false + usergrid.management.notify_sysadmin_of_new_organizations=false + usergrid.management.notify_sysadmin_of_new_admin_users=false + + ###################################################### + # URLs + # Redirect path when request come in for TLD + + usergrid.redirect_root=https://localhost:8080/status + usergrid.view.management.organizations.organization.activate=https://localhost:8080/accounts/welcome + usergrid.view.management.organizations.organization.confirm=https://localhost:8080/accounts/welcome + usergrid.view.management.users.user.activate=https://localhost:8080/accounts/welcome + usergrid.view.management.users.user.confirm=https://localhost:8080/accounts/welcome + usergrid.organization.activation.url=https://localhost:8080/management/organizations/%s/activate + usergrid.admin.activation.url=https://localhost:8080/management/users/%s/activate + usergrid.admin.resetpw.url=https://localhost:8080/management/users/%s/resetpw + usergrid.admin.confirmation.url=https://localhost:8080/management/users/%s/confirm + usergrid.user.activation.url=https://localhost:8080%s/%s/users/%s/activate + usergrid.user.confirmation.url=https://localhost:8080/%s/%s/users/%s/confirm + usergrid.user.resetpw.url=https://localhost:8080/%s/%s/users/%s/resetpw + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/installation/ug1-launcher-quick-start.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/installation/ug1-launcher-quick-start.txt b/content/docs/_sources/installation/ug1-launcher-quick-start.txt new file mode 100644 index 0000000..8399522 --- /dev/null +++ b/content/docs/_sources/installation/ug1-launcher-quick-start.txt @@ -0,0 +1,72 @@ +# Usegrid 1: Launcher Quick-start + +## Requirements + +* [JDK 1.7](http://www.oracle.com/technetwork/java/javase/downloads/index.html) +* [Maven](http://maven.apache.org/) + +## Download + +### Download2 + +Start by [downloading our latest code](https://github.com/apache/incubator-usergrid/archive/master.zip) and extract it. + +#### Building 3 + +From the command line, navigate to stack directory and type the following: + + mvn clean install -DskipTests=true + +## Running + +Usergrid-core contains the persistence layer and shared utilities for powering the Usergrid service. The services layer is contained in usergrid-services and exposes a higher-level API that's used by the usergrid-rest web services tier. + +You can run Usergrid from the command-line from the +jar in the usergrid/standalone project: + + cd launcher; java -jar target/usergrid-launcher-*.jar + +After startup, your instance will be available on localhost, port 8080. +To check itâs running properly, you can try loading our status page: + + curl http://localhost:8080/status + +You can also run it as a webapp in Tomcat, by deploying the ROOT.war file generated in the usergrid/rest project. + +## Getting Started with the HTTP API + +Start by creating an Organization. Itâs the top-level structure in Usergrid: +all Apps and Administrators must belong to an Organization. Hereâs how you create one: + + curl -X POST \ + -d 'organization=myfirstorg&username=myadmin&name=Admin&email=ad...@example.com&password=password' \ + http://localhost:8080/management/organizations + +You can see that creating an Organization creates an Administrator in the process. Letâs authenticate as him: + + curl 'http://localhost:8080/management/token?grant_type=password&username=myadmin&password=password' + +This will return an access\_token. Weâll use this to authenticate the next two calls. +Next, letâs create an Application: + + curl -H "Authorization: Bearer [the management token from above]" \ + -H "Content-Type: application/json" \ + -X POST -d '{ "name":"myapp" }' \ + http://localhost:8080/management/orgs/myfirstorg/apps + +⦠And a User for the Application: + + curl -H "Authorization: Bearer [the management token from above]" \ + -X POST "http://localhost:8080/myfirstorg/myapp/users"; \ + -d '{ "username":"myuser", "password":"mypassword", "email":"u...@example.com" }' + +Letâs now generate an access token for this Application User: + + curl 'http://localhost:8080/myfirstorg/myapp/token?grant_type=password&username=myuser&password=mypassword' + +This will also send back an access\_token, but limited in scope. +Letâs use it to create a collection with some data in it: + + curl -H "Authorization: Bearer [the user token]" \ + -X POST -d '[ { "cat":"fluffy" }, { "fish": { "gold":2, "oscar":1 } } ]' \ + http://localhost:8080/myfirstorg/myapp/pets http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/installation/ug2-deploy-to-tomcat.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/installation/ug2-deploy-to-tomcat.txt b/content/docs/_sources/installation/ug2-deploy-to-tomcat.txt new file mode 100644 index 0000000..10ed013 --- /dev/null +++ b/content/docs/_sources/installation/ug2-deploy-to-tomcat.txt @@ -0,0 +1,167 @@ +# Usergrid 2: Deploy to Tomcat + +__NOTE__: Beware that Usergrid 2 is UNRELEASED SOFTWARE + +## Requirements + +* [JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) +* [Maven 3.2+](http://maven.apache.org/) +* [Tomcat 7+](https://tomcat.apache.org/download-70.cgi) +* [Cassandra 1.2.1*](http://cassandra.apache.org/download/) +* [ElasticSearch 1.4+](https://www.elastic.co/downloads/elasticsearch) +* [Usergrid 2.0](https://github.com/apache/incubator-usergrid/tree/two-dot-o) + +##Running + + +1. Start up Cassandra [^1] + a. To do this you can navigate to the cassandra folder and run ```./bin/cassandra ``` +2. Start up Elasticsearch + a. To do this you can navigate to the folder where you extracted elasticsearch and run ```/bin/elasticsearch``` + +###Running Usergrid + +####Build The Java Sdk + +1. Navigate to where you cloned the usergrid repo +2. Navigate to the ```sdks/java``` directory +3. Run ```mvn clean install``` + +####Build The Stack Itself + +1. Navigate to the ```stack``` directory. +2. Run ```mvn clean install -DskipTests``` +3. This will generate a war at ```rest/target/ROOT.war``` + +####Deploying the Stack Locally +1. Take this war and deploy it on downloaded tomcat. +1. In the lib directory of the tomcat you must also put usergrid-deployment.properties. ( An example file is provided below) +1. Start up Tomcat + a. To do this you can navigate to folder where Tomcat is install and run ```./bin/catalina.sh start``` +1. Go to a web browser and input the following to initilizing the database ```localhost:8080/system/database/setup```. + a. The credentials it asks for are the admin credentialls and password as defined in the usergrid-deployment.properties. + b. You can also do a curl call with basic auth to automatically authenticate the call instead of using the web browser. +1. Then using the same steps as before call ```localhost:8080/system/superuser/setup``` + +The stack is now ready to be queried against, but to get the most out of it you'll need to initilize and use our portal! + +####Running The Portal Locally +#####Requirments +[nodejs 0.10+](https://nodejs.org/download/) + +1. Make sure you've installed node.js above. Any version above .10 or .10 should work fine. +2. Navigate to ```incubator-usergrid/portal```. +3. Open config.js and make sure the override URL is pointing to your local tomcat. +4. Now in the portal folder run the following command ```./build.sh dev``` +5. The portal should automatically open ready for use! + +Now usergrid is fully ready to use! Feel free to query against it or use it however you like! + + + +Example __usergrid-deployment.properties__ file +--- +``` +# core persistence properties + +cassandra.embedded=false +cassandra.version=1.2.18 +cassandra.timeout=2000 + +collections.keyspace=Usergrid_Applications +collections.keyspace.strategy.options=replication_factor:1 +collections.keyspace.strategy.class=org.apache.cassandra.locator.SimpleStrategy + +collection.stage.transient.timeout=60 + +hystrix.threadpool.graph_user.coreSize=40 +hystrix.threadpool.graph_async.coreSize=40 + +elasticsearch.embedded=false +elasticsearch.cluster_name=elasticsearch +elasticsearch.index_prefix=usergrid +elasticsearch.hosts=127.0.0.1 +elasticsearch.port=9300 + +elasticsearch.force_refresh=true + +index.query.limit.default=100 + +# Max Cassandra connections, applies to both CP and EM +cassandra.connections=600 + +###################################################### +# Minimal Usergrid configuration properties for local Tomcat and Cassandra +# + +cassandra.url=127.0.0.1:9160 + +cassandra.keyspace.strategy=org.apache.cassandra.locator.SimpleStrategy +cassandra.keyspace.strategy.options.replication_factor=1 + +###################################################### +# Custom mail transport + +mail.transport.protocol=smtps +mail.smtps.host=smtp.gmail.com +mail.smtps.port=465 +mail.smtps.auth=true +mail.smtps.username= +mail.smtps.password= +mail.smtps.quitwait=false + + +###################################################### +# Admin and test user setup + +usergrid.sysadmin.login.name=superuser +usergrid.sysadmin.login.email=mys...@example.com <--- Change this +usergrid.sysadmin.login.password=pwHERE <--- Change this +usergrid.sysadmin.login.allowed=true +usergrid.sysadmin.email=mys...@example.com <--- Change this + +usergrid.sysadmin.approve.users=false +usergrid.sysadmin.approve.organizations=false + +# Base mailer account - default for all outgoing messages +usergrid.management.mailer=User <mys...@example.com> <--- Change this + +usergrid.setup-test-account=true + +usergrid.test-account.app=test-app +usergrid.test-account.organization=test-organization +usergrid.test-account.admin-user.username=test +usergrid.test-account.admin-user.name=Test User +usergrid.test-account.admin-user.email=mys...@example.com <---Change this +usergrid.test-account.admin-user.password=test + +###################################################### +# Auto-confirm and sign-up notifications settings + +usergrid.management.admin_users_require_confirmation=false +usergrid.management.admin_users_require_activation=false + +usergrid.management.organizations_require_activation=false +usergrid.management.notify_sysadmin_of_new_organizations=true +usergrid.management.notify_sysadmin_of_new_admin_users=true +###################################################### +# URLs + +# Redirect path when request come in for TLD +usergrid.redirect_root=http://localhost:8080/status + +usergrid.view.management.organizations.organization.activate=http://localhost:8080/accounts/welcome +usergrid.view.management.organizations.organization.confirm=http://localhost:8080/accounts/welcome +usergrid.view.management.users.user.activate=http://localhost:8080/accounts/welcome +usergrid.view.management.users.user.confirm=http://localhost:8080/accounts/welcome + +usergrid.organization.activation.url=http://localhost:8080/management/organizations/%s/activate +usergrid.admin.activation.url=http://localhost:8080/management/users/%s/activate +usergrid.admin.resetpw.url=http://localhost:8080/management/users/%s/resetpw +usergrid.admin.confirmation.url=http://localhost:8080/management/users/%s/confirm +usergrid.user.activation.url=http://localhost:8080%s/%s/users/%s/activate +usergrid.user.confirmation.url=http://localhost:8080/%s/%s/users/%s/confirm +usergrid.user.resetpw.url=http://localhost:8080/%s/%s/users/%s/resetpw +``` + +[^1]: You can start up cassandra and elasticsearch in any order but for the sake of ordered lists I put Cassandra first. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/introduction/async-vs-sync.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/introduction/async-vs-sync.txt b/content/docs/_sources/introduction/async-vs-sync.txt new file mode 100644 index 0000000..fe1f721 --- /dev/null +++ b/content/docs/_sources/introduction/async-vs-sync.txt @@ -0,0 +1,25 @@ +# Async vs. sync calls +The Usergrid SDKs work by making RESTful API calls from your application to the API. In some cases, both synchronous and asynchronous calls are supported for most methods, as in the case of the Usergrid Android SDK, while in others only asynchronous calls are supported, as in the Usergrid JavaScript SDK. The following is a brief explanation of synchronous vs. asynchronous API calls. + +## Synchronous +If an API call is synchronous, it means that code execution will block (or wait) for the API call to return before continuing. This means that until a response is returned by the API, your application will not execute any further, which could be perceived by the user as latency or performance lag in your app. Making an API call synchronously can be beneficial, however, if there if code in your app that will only execute properly once the API response is received. + +## Asynchronous +Asynchronous calls do not block (or wait) for the API call to return from the server. Execution continues on in your program, and when the call returns from the server, a "callback" function is executed. For example, in the following code using the Usergrid JavScript SDK, the function called dogCreateCallback will be called when the create dog API call returns from the server. Meanwhile, execution will continue: + + function dogCreateCallback(err, dog) { + alert('I will probably be called second'); + if (err) { + //Error - Dog not created + } else { + //Success - Dog was created + + } + } + + client.createEntity({type:'dogs'}, dogCreateCallback); + alert('I will probably be called first'); + +The result of this is that we cannot guarantee the order of the two alert statements. Most likely, the alert right after the createEntity function call will be called first since the API call will take a second or so to complete. + +The important point is that program execution will continue, and asynchronously, the callback function will be called once program execution completes. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/introduction/data-model.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/introduction/data-model.txt b/content/docs/_sources/introduction/data-model.txt new file mode 100644 index 0000000..0278b97 --- /dev/null +++ b/content/docs/_sources/introduction/data-model.txt @@ -0,0 +1,76 @@ +# Usergrid Data model + +Usergrid models the data for your apps as application-specific collections of data entities managed within an organization. The following is an overview of the component hierarchy that makes up the data model, and is intended to help you understand how data is stored, managed and accessed. + +## Organizations +An organization contains one or more applications, and represents administrator-level access. Multiple accounts may be given administrator access to an organization. Accounts can also be members of multiple organizations. + +An organization with the same name as your username is automatically created for you when you sign up. By default, you are assigned as the administrator of this organization. + +## Applications +In Usergrid, you can create one or more applications within an organization. Applications represent an instance of application data associated with an app, and you may create as many applications as you wish. This allows you to utilize the backend in a way that corresponds to your development process. For example, you might create separate applications for development and production instances of your app. By default, all organization have a sandbox application (see Using a Sandbox Application for important information regarding the default sandbox application). + +Each application provides the infrastructure for storing, retrieving, updating and deleting the entities and collections associated with a specific app instance. + +## Collections +Usergrid stores all data entities in uniquely-named collections. Collections are created automatically for every entity type, including custom entities, and are named using the plural form of the entity type they store. For example, all user entities are stored in the /users collection, and all device entities in the /devices collection. An entity can belong to only one collection. + +Currently, collections cannot be renamed or deleted; however, all of the data entities in a collection can be updated or deleted. + +## Entities +An entity represents a basic, JSON-formatted data object that is used by your app, such as a user, device, event or asset. Unlike records in conventional database tables, which have a rigid schema that defines what they can store and how they can be related to each other, Usergrid entities are very flexible. This makes Usergrid a powerful solution for managing data for modern applications, where people, places, and content often need to be associated in a way that is most appropriate from a user perspective. + +Here is a simple example of an entity: + + { + "uuid" : "5c0c1789-d503-11e1-b36a-12313b01d5c1", + "type" : "user", + "created" : 1343074620374, + "modified" : 1355442681264, + "username" : "john.doe", + "email" : "jdo...@mail.com", + "name" : "John Doe" + } + +## Default entities +The following entity types are predefined in Usergrid. For more details, see Default Data Entity Types. + +* user +* group +* role +* application +* activity +* device +* asset +* folder +* event +* notifier +* notification +* receipt + +## Properties + +A data entity is a set of properties, which can each contain any JSON-representable value, including a nested JSON document. All entities have predefined properties, but you are free to define any number of custom properties for any entity. Default properties require specific data types for validation purposes, while custom properties can be any JSON data type. Most predefined and all application-defined entity properties are indexed, allowing you to query collections quickly and easily. + +Individual or multiple properties can be updated in a single operation; however, partial updating of nested JSON documents is not supported. This means that all properties of a nested document must be provided in a PUT request for the update of the nested document to be processed, even if the some of the values have not changed. + +## Default properties +At a minimum, each entity is defined by two properties, both of which are strings: type and UUID. The entity 'type' is the singular form of the collection the entity is stored in. For example, an entity in the 'users' collection has an entity type of 'user'. The entity 'UUID' is an immutable universally unique identifier, which can be used to reference the entity. A UUID is automatically generated for every entity when it is created. You can also create custom entities and entity properties; however, Usergrid reserves certain entity types with pre-defined properties by default. For a complete list of reserved entities and properties, see Default Data Entity Types. + +When you access the system via the API, youâll always provide your organization UUID or name, application UUID or name, and typically the UUID or name of the entity youâre modifying or retrieving. + +All entities have the following default properties: + ++------------+--------+---------------------------------------------------------------------+ +| Property | Type | Description | ++------------+--------+---------------------------------------------------------------------+ +| uuid | UUID | Entity unique id | ++------------+--------+---------------------------------------------------------------------+ +| type | string | entity type (for example, user) | ++------------+--------+---------------------------------------------------------------------+ +| created | long | UTC timestamp in milliseconds of when the entity was created | ++------------+--------+---------------------------------------------------------------------+ +| modified | long | UTC timestamp in milliseconds of when the entity was last modified | ++------------+--------+---------------------------------------------------------------------+ + +Custom entities also have an optional name property that is a string identifier. http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/introduction/usergrid-features.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/introduction/usergrid-features.txt b/content/docs/_sources/introduction/usergrid-features.txt new file mode 100644 index 0000000..5e57071 --- /dev/null +++ b/content/docs/_sources/introduction/usergrid-features.txt @@ -0,0 +1,81 @@ +# Usergrid Features + +Usergrid provides developers with access to a flexible data store and enables you to quickly integrate valuable features into your app, including social graphs, user management, data storage, push notifications, performance monitoring, and more. + +With Usergrid, developers can set up their own cloud-based data platform in minutes instead of months â no server-side coding or back-end development needed. This allows your developers to focus on developing the rich features and user experience that truly differentiate your app, rather than on the time-consuming details of implementing core back-end services and infrastructure. + +## Data storage & management + +### Application data + +At the core of Usergrid is a flexible platform that can store any type of application data, from simple records like a catalog of books to complex associations like user relationships. No matter what type of data drives your app, you can store it as collections of data entities and immediately perform complex queries or full-text searches on any field. You can also create custom entities with custom properties, giving you the ability to store data and context in a way that makes sense for your app. + +To learn more about entities and collections, see Usergrid Data model. + +For a complete list of the default data entities available, see Default Data Entity Types. + +### Files & assets + +Images, video, and audio are key components of a great app experience. With Usergrid, you can upload and retrieve binary objects from the same data store as the rest of your application data, eliminating the need to set up content delivery networks (CDNs) and easing implementation. We handle all the back-end details that keep your content quickly accessible. + +To learn more about files and asset storage, see Uploading files and assets . + +## Flexible data querying + +One of Usergrid' most powerful features is the ability to perform SQL-style queries and full-text searches on data entities, as well as their properties. This lets you quickly retrieve specific data entities based on multiple criteria, then utilize that data to power social features, target push notifications, perform user analysis, and more. + +Learn more about querying app data, see Data query overview. + +## Social + +### Entity relationships + +You can create relationships between data entities to help build features, improve user experience, and contextualize data. For example, you might associate a user with their devices to capture valuable geolocation data, create relationships between users to build social graphs, or implement popular features such as activity streams. + +To learn more about entity relationships, see Entity connections. + +### Activity streams + +A key aspect of social networking apps is the ability to provide and publish data streams of user actions, such as ongoing lists of comments, activities, and tweets. Usergrid simplifies management and routing of these data streams by providing an activity entity that is specifically designed to automatically create a relationship between activities and the user who created them. + +To learn more about activities and activity feeds, see Activity feeds. + +## User management + +### Registration and login + +You can easily add and manage users by providing the core services necessary to handle secure registration and log in, including OAuth 2.0-compliant client authentication. In addition, any number of default or custom data entities and properties can be associated with a user entity to create complete user profiles. + +To learn more about user management, see User. + +To learn more about authentication, see Authenticating users and application clients. + +### Roles & permissions + +Applications often require the ability to configure fine-grain control of user access to data, features and functionality. Usergrid solves the implementation details of user access with roles and permissions. Simply create roles that represent user types or access levels, such as Administrator, then assign the necessary permissions to that role. With a single API call, you can then associate your roles with any user or group of users. + +To learn more about user roles and permissions, see Managing access by defining permission rules. + +### Groups + +Groups are a flexible way to organize your users based on any number of criteria. For example, you might group users based on interests or location to more effectively deliver relevant content, target offers, or customize campaigns. You can also take advantage of the groups entity to enable group-based social networking activities, such as allowing your users to create private information feeds or circles of friends. + +To learn more about groups, see Working with group data. + +### Third-party authentication + +In addition to supporting user management and OAuth-based login for your app, Usergrid also makes it easy to integrate third-party authentication through such popular services as Facebook, Twitter and other OAuth-enabled accounts. Providing third-party sign-in can improve user experience, while increasing adoption, giving you access to valuable information from social networks and services. + +To learn more about using third-party sign-in, see Facebook sign in. + +## Geolocation + +The device entity allows you to capture geolocation data from your users' GPS-enabled devices to more effectively target campaigns, push notifications, offers and more. Geolocation also gives you an important data point for contextualizing and analyzing trends and user behavior. + +To learn more about geolocation, see Geolocation. + +## Push notifications + +Push notifications are the most effective way to engage your users with relevant content, and thanks to Usergrid, implementing them can be done in minutes. Simply register your app and your user's devices with a notification provider, such as Apple Push Notification Service or Google Cloud Messaging, then use the Usergrid notification entity to send millions of push notifications a month at no cost. When used in conjunction with queries of user and application data, push notifications become a powerful tool for leveraging user data, ensuring relevancy and driving engagement. + +To learn more about push notifications, see Push notifications overview. http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/orgs-and-apps/admin-user.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/orgs-and-apps/admin-user.txt b/content/docs/_sources/orgs-and-apps/admin-user.txt new file mode 100644 index 0000000..87b96f9 --- /dev/null +++ b/content/docs/_sources/orgs-and-apps/admin-user.txt @@ -0,0 +1,352 @@ +# Admin user$ +An admin user has full access to perform any operation on all organization accounts of which the admin user is a member. Using the API Services BaaS API, you can create, update, or retrieve an admin user. You can also set or reset an admin user's password, activite or reactivate an admin user, and get an admin user's activity feed. + +In addition, you can add, retrieve, or remove an admin user from an organization. For information on these organization-related operations, see [Organization](organization.html). + +__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. + +## Creating an admin user +Use the POST method to create an admin user. + +### Request URI + + POST /management/organizations/{org}/users {request body} + +In the request body send a JSON object that represents the new user, for example: + + { + "username" : "jim.admin", + "email" : "jim.ad...@gmail.com", + "name" : "Jim Admin", + "password" : "test12345" + } + + +### Example - Request + + curl -X -i POST "https://api.usergrid.com/management/organizations/my-org/users"; -d '{"username":"jim.admin","name":"Jim Admin","email":"jim.ad...@gmail.com","password":"test12345"}' + +### Example - Response + + { + "action": "post", + "status": "ok", + "data": { + "user": { + "applicationId": "00000000-0000-0000-0000-000000000001", + "username": "jim.admin", + "name": "Jim Admin", + "email": "jim.ad...@gmail.com", + "activated": true, + "disabled": false, + "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591", + "adminUser": true, + "displayEmailAddress": "jim.admin <jim.ad...@gmail.com>", + "htmldisplayEmailAddress": "jim.admin <a href="mailto:jim.ad...@gmail.com";>jinm.ad...@gmail.com</a>" + } + }, + "timestamp": 1349390189106, + "duration": 11808 + } + + +## Updating an admin user +Use the PUT method to update an admin user. + +### Request URI + + PUT /management/organizations/{org}/users/{user|username|email|uuid} {request body} + +Parameters + +Parameter Description +--------- ----------- +User identifier Username, name, email address, or UUID. +request body JSON object containing propties you would like to add/update on user. + +For example, to add city and state to user, send this: + + { + "city" : "San Francisco", + "state" : "California" + } + +### Example - Request + + curl -X -i PUT "https://api.usergrid.com/management/organizations/my-org/users/jim.admin"; -d '{"city":"San Francisco","state":"California"}' + +### Example - Response + + { + "action": "update user info", + "timestamp": 1349479321874, + "duration": 0 + } + +## Getting an admin user +Use the GET method to retrieve details about an admin user. + +### Request URI + + GET /management/organizations/{org}/users/{user|username|email|uuid} + +Parameters + +Parameter Description +--------- ----------- +User identifier Admin username, name, email address, or UUID. + + +### Example - Request + + curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin"; + +### Example - Response + + { + "action": "get admin user", + "status": "ok", + "data": { + "username": "jim.admin", + "token": "YWMt4NqE8Q9GEeLYJhIxPSiO4AAAATo5fQfcG0cEd2h9nwmDmRorkNNrEeQyDOF", + "email": "edo...@gmail.com", + "organizations": { + "jim.admin": { + "users": { + "jim.admin": { + "applicationId": "00000000-0000-0000-0000-000000000001", + "username": "jim.admin", + "name": "Jim Admin", + "email": "jim.ad...@gmail.com", + "activated": true, + "disabled": false, + "uuid": "328b526e-cd0c-11e1-bcf8-12424d1c4491", + "adminUser": true, + "displayEmailAddress": "jim.admin <jim.ad...@gmail.com>", + "htmldisplayEmailAddress": "jim.admin <<a href="mailto:jim.ad...@gmail.com";>jim.ad...@gmail.com>" + }, + ... + "adminUser": true, + "activated": true, + "name": "edort1", + "applicationId": "00000000-0000-0000-0000-000000000001", + "uuid": "328b526e-cd0c-11e1-bcf8-12424d1c4491", + "htmldisplayEmailAddress": "jim.admin <<a href="mailto:jim.ad...@gmail.com";>jim.ad...@gmail.com>>", + "displayEmailAddress": "jim.admin <jim.ad...@gmail.com>", + "disabled": false + }, + "timestamp": 1349480786906 + } + +## Setting an admin user's password +Use the PUT method to update an admin user's password. + +### Request URI + + PUT /management/users/{user|username|email|uuid}/password {request body} + +Parameters + +Parameter Description +--------- ----------- +User identifier Admin username, name, email address, or UUID. + +Expects new and old password to be sent in request body: + + { + "password": <old_password> + "newpassword":<new_password> + } + +### Example - Request + + curl -X -i PUT "https://api.usergrid.com/management/users/jim.admin/password"; -d '{"oldpassword":"test123", "newpassword":"mynewpassword"}' + +### Example - Response + + { + "action": "set user password", + "timestamp": 1349714010142, + "duration": 0 + } + +## Resetting an admin user's password +Resetting an admin user's password is a two step process. In the first step, you initiate the password reset. This returns a browser page. The page includes a field for the user to enter his or her email address, and a field to enter a response to a Captcha challenge. In the second step, you handle the user's responses from the form. + +### Initiating a password reset +Use the GET method to initiate the password reset. + +### Request URI + + GET /management/organizations/{org}/users/resetpw + +### Example - Request + + curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/resetpw"; + +### Example - Response + + <!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" /> + <script type="text/javascript">> + var RecaptchaOptions = { + theme : 'clean' + }; + </script> + </head> + <body> + + <div class="dialog-area"> + <div class="dialog-form-message">Incorrect Captcha, try again...</div> + <form class="dialog-form" action="" method="post"> + <fieldset> + <p> + <label for="email">Please type your <strong>email + address</strong> or <strong>username</strong> below.</label> + </p> + <p> + <input class="text_field" id="email" name="email" type="text" /> + </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"> + <button type="submit">Submit</button> + </p> + </fieldset> + </form> + </div> + </pre> + +## Completing a password reset +Use the POST method to complete the password reset. + +### Request URI + + POST /management/organizations/{org}/users/resetpw {request body} + +In the request body send parameters and value for the Captcha challenge, the admin user's response to the Captcha challenge, and the admin user's email address, for example: + + { + "recaptcha_response_field" : "Atistophanes tseFia", + "recaptcha_challenge_field" : "Atistophanes tseFia", + "email" : "jim.ad...@gmail.com" + } + +### Example - Request + + curl -X -i POST "https://api.usergrid.com/management/organizations/my-org/users/resetpw"; -d '{"recaptcha_response_field":"Atistophanes tseFia","recaptcha_challenge_field":"Atistophanes tseFia","email":"jim.ad...@gmail.com"}' + +### Example - Response + + { + "action": "reset user password", + "timestamp": 13546154010321, + "duration": 0 + } + +## Activating an admin user +Use the GET method to activate an admin user from a link provided in an email notification. + +### Request URI + + GET /management/organizations/{org}/users/{user|username|email|uuid}/activate?token={token}&confirm={confirm_email} + +Parameters + +Parameter Description +--------- ----------- +User identifier Admin username, name, email address, or UUID. +string token Activation token (supplied via email). +confirm_email Send confirmation email (false is the default). + +### Example - Request + + curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/activate?token=33dd0563-cd0c-11e1-bcf7-12313d1c4491"; + +### Example - Response + + { + "action": "activate user", + "timestamp": 1349718021324, + "duration": 0 + } + +## Reactivating an admin user +Use the GET method to reactivate an admin user. + +### Request URI + + GET /management/organizations/{org}/users/{user|username|email|uuid}/reactivate + +Parameters + +Parameter Description +--------- ----------- +User identifier Admin username, name, email address, or UUID. + +## Example - Request + + curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/reactivate"; + +### Example - Response + + { + "action": "reactivate user", + "timestamp": 1349735217217, + "duration": 3541 + } + +## Getting an admin user's activity feed +Use the GET method to retrieve an admin user's activity feed. + +### Request URI + + GET /management/organizations/{org}/users/{user|username|email|uuid}/feed + +Parameters + +Parameter Description +--------- ----------- +User identifier Admin username, name, email address, or UUID. + +### Example - Request + + curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/feed"; + +### Example - Response + + { + "action": "get admin user feed", + "status": "ok", + "entities": [ + { + "uuid": "cf3e981c-fe80-11e1-95c8-12331b144c65", + "type": "activity", + "created": 1347643370454, + "modified": 1347643370454, + "actor": { + "displayName": "jim.admin", + "objectType": "person", + "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591", + "entityType": "user" + }, + "category": "admin", + "metadata": { + "cursor": "gGkAAQMAgGkABgE5xc3r1gCAdQAQz02YHP6QEeGVyBIxOxIsVgCAdQAQz4ZbYf6QEeGVyBIxOxIsVgA", + "path": "/users/327b527f-cd0c-11e1-bcf7-12313d1c4491/feed/cf4d981c-fe90-11e1-95c8-12313b122c56" + }, + "object": { + ... + }, + "published": 1342198809251, + "title": "<a mailto="jim.admingmail.com">jim.admin (jim.ad...@gmail.com)</a> created a new organization account named jim.admin", + "verb": "create" + } + ], + "timestamp": 1349735719320, + } http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/orgs-and-apps/application.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/orgs-and-apps/application.txt b/content/docs/_sources/orgs-and-apps/application.txt new file mode 100644 index 0000000..7495aee --- /dev/null +++ b/content/docs/_sources/orgs-and-apps/application.txt @@ -0,0 +1,100 @@ +# Application +You can create a new application in an organization through the Admin portal. The Admin portal creates the new application by issuing a post against the management endpoint (see the "Creating an organization application" section in Organization for details). If you need to create an application programmatically in your app, you can also use the API to do this. You can access application entities using your app name or UUID, prefixed with the organization name or UUID: + + https://api.usergrid.com/{org_name|uuid}/{app_name|uuid} + +Most mobile apps never access the application entity directly. For example you might have a server-side web app that accesses the application entity for configuration purposes. If you want to access your application entity programmatically, you can use the API. + +## Creating an application +To create an application you POST a JSON object containing (at a minimum) the name of the new application. +You will also need to pass authentication credentials. + +### Request URI + + POST /management/organizations|orgs/{org_name}|{org_uuid}/apps {request body} + +Parameters + +Parameter Sent in Description +--------- ------- ----------- +grant_type Query string Only the value 'client_credentials' is supported. +client_id Query string The org-level client id for your org, found in the 'Org Administration' menu of Usergrid portal. +client_secret Query string The org-level client secret for your org, found in the 'Org Administration' menu Usergrid portal. +name Request Body The name of the application. + +### Example - Request + + curl -X -i POST "https://api.usergrid.com/management/orgs/testorg/apps?grant_type=client_credentials&client_id=b3U68vghI6FmEeKn9wLoGtzz0A&client_secret=b3U6ZuZ5_U8Y-bOaViJt0OyRkJFES-A"; -d '{"name":"testapp1"}' + +### Example - Response + + { + "action": "new application for organization", + "timestamp": 1338914698135, + "duration": 701 + } + +## Generating application credentials +Use the POST method to generate the client ID and client secret credentials for an application in an organization. + +### Request URI + + POST /organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}|{uuid}/credentials + +Parameters + +Parameter Description +--------- ----------- +string org_name|arg uuid Organization name or organization UUID. +string app_name|arg uuid Application name or application UUID. + +Note: You also need to provide a valid access token with the API call. See [Authenticating users and application clients](../security_and_auth/authenticating-users-and-application-clients.html) for details. + +### Example - Request + + curl -X POST "https://api.usergrid.com/management/orgs/testorg/apps/testapp1/credentials"; + +### Example - Response + + { + "action": "generate application client credentials", + "timestamp": 1349815979529, + "duration": 535, + "credentials": { + "client_id": "YXA7ygil-f3TEeG-yhIxPQK1cQ", + "client_secret": "YXA65gYlqja8aYYSAy8Ox3Vg5aRZp48" + } + } + +## Getting application credentials +Use the GET method to retrieve the client ID and client secret credentials for an application in an organization. + +### Request URI + + GET /organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}|{uuid}/credentials + +Parameters + +Parameter Description +--------- ----------- +string org_name|arg uuid Organization name or organization UUID. +string app_name|arg uuid Application name or application UUID. + +Note: You also need to provide a valid access token with the API call. See [Authenticating users and application clients](../security_and_auth/authenticating-users-and-application-clients.html) for details. + +### Example - Request + + curl -X GET "https://api.usergrid.com/management/orgs/testorg/apps/testapp1/credentials"; + +### Example - Response + + { + "action": "get application client credentials", + "timestamp": 1349816819545, + "duration": 7, + "credentials": { + "client_id": "YXA7ygil-f3TEeG-yhIxPQK1cQ", + "client_secret": "YXA65gYlqja8aYYSAy8Ox3Vg5aRZp48" + } + } + http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/_sources/orgs-and-apps/managing.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/orgs-and-apps/managing.txt b/content/docs/_sources/orgs-and-apps/managing.txt new file mode 100644 index 0000000..3c09807 --- /dev/null +++ b/content/docs/_sources/orgs-and-apps/managing.txt @@ -0,0 +1,50 @@ +# Organization & application management +Your application can use the App Services API to request a variety of management operations on App Services resources. For example, your application can request an access token to use in operations on entities and collections. Or it can create an organization to contain the applications, entities, and collections for a company, team, or project. + +Your application makes requests through the API using HTTP methods such as GET, POST, PUT, and DELETE, and specifies the pertinent resource URL. For management operations, the URL begins with ``/management/``. See [Using the API](../getting-started/using-the-api.html) for general usage information, such as how to construct an API request. + +The following table lists and describes resources accessible through the App Services API on which your application can perform management operations. Click on a resource for further details about the resource and its methods. + +<table class="usergrid-table"> +<tr> + <th> + Resource + </th> + <th> + Description + </th> +</tr> +<tr> + <td> + [Access Token](../security-and-auth/authenticating-users-and-application-clients.html) + </td> + <td> + Carries the credentials and authorization information needed to access other resources through the Usergrid API. + </td> +</tr> +<tr> + <td> + [Client Authorization](../security-and-auth/authenticating-api-requests.html) + </td> + <td> + Authorizes the client. + </td> +</tr> +<tr> + <td> + [Organization](organization.html) + </td> + <td> + The highest level structure in the Usergrid data hierarchy. + </td> +</tr> +<tr> + <td> + [Admin User](adminuser.html) + </td> + <td> + A user that has full access to perform any operation on all organization accounts of which the user is a member. + </td> +</tr> +</table> +
