Data model

App Services models the data for your applications as collections of entities. An entity can represent a user of your application, the content for your application, or other application data. A collection collects entities. For example, all user entities are members of a users collection.

Entities and collections are managed within an organization. An organization contains applications, which are workspaces for the applications that you build.

Entities

An entity represents a basic object related to your application such as a user, or application content such as a customer or inventory item, or other application-related data such as an event.

Each entity is defined at a minimum by a unique UUID and entity type, which is a string such as "user", "group", or "location". The following entity types are predefined in App Services:

• user
• group
• role
• application
• activity
• device
• asset
• folder
• event
• notifier
• notification
• receipt

Each entity type is stored in its own root collection that contains all entities of that type. Root collections are automatically named using the plural form of the entity type, for example, “/users”, “/groups”, and “/roles”.

You can also create any additional type of entity that you want. These are called “dynamic” (or “custom”) entities. Dynamic entities are automatically stored in a collection whose name is the pluralized form of the entity type. For example, if you create an entity of type “cat”, App Services stores the entity in a collection named “cats”. App Services ensures that entity types are singular and collection names are plural.

Each entity has a unique UUID assigned to it. You can also assign your own id property to an entity.

All entities have predefined properties. You can also define any number of additional properties for an entity. These are called “dynamic” (or “custom”) properties. Predefined properties require specific data types for validation purposes, while dynamic properties can be any JSON data type. App Services relies on JSON representation because it is supported by almost all languages and can represent most types of data and content.

All entities have the following default properties:

Dynamic entities also have an optional name property that is a string identifier.

Entity property values are case insensitive. This means that you can search for a user whose name is john.doe like this:

GET /{org_id}/{app_id}//users?ql=select * where name ='john.doe'

or like this:

GET /{org_id}/{app_id}//users?ql=select * where name ='john.DOE'

Note:

• For entities of type user, the username property value must be unique.
• For all other entity types, the name property value must be unique and is immutable. This means that once you set it, it cannot be changed.

Here is a simple example of an entity:

{
  "uuid" : "5c0c1789-d503-11e1-b36a-12313b01d5c1",
  "type" : "user",
  "created" : "1343074620374,
  "modified" : 1355442681264,
  "username" : "john.doe",
  "email" : "jdoe57@mail.com",
  "name" : "John Doe"
}

Collections

Entities are stored in collections, and for every entity type, there’s a root collection that contains all entities of that type. For example all user entities are in the /users root collection, and all devices entities are in the /devices root collection. An entity can belong to only one collection.

You can create collections in several ways:

• By creating an entity. When a new entity is created, a collection to hold that entity is also created automatically if none exists.
• By using the Admin Portal (https://apigee.com/usergrid). Sign in, then choose the collections button on the left hand side. Finally, choose "add new collection" in the upper right hand corner of the page.
• By posting directly to the API endpoint:

  POST /{org_id}/{app_id}/{collection}

  where {org_id} is the organization UUID or organization name, {app_id} is the application UUID or application name, and {collection} is the collection name.

Entities can be connected to entities in the same or other collections. For example, the following connects the user entity named "john.doe" to the food entity named "pizza" with a "likes" relationship:

POST https://api.usergrid.com/my-org/my-app/users/john.doe/likes/food/pizza

Collections can be searched in various ways. Most predefined and all application-defined entity properties are indexed, allowing you to query collections more easily and more quickly. For example, you can query all users in a group that share a city property containing the word California.

Organizations and applications

An organization represents the highest level of the App Services data hierarchy. It contains applications (and the entities and collections they contain) and is associated with one or more administrators. An organization allows multiple applications to be shared within the organization with other administrators.

When you sign up on the App Services site, you create an organization for your company, team, or project and an individual account for yourself that has admin rights to that organization. Your individual account can be a member of multiple organizations and multiple accounts can have admin rights to an organization.

Using the APP Services API, you can create one or more applications in an organization. Think of an application as a workspace for an application that you (or someone else) builds. Each application (workspace) provides the infrastructure for storing the entities and collections associated with the built application.