Creating relationships between entities
One of the most useful features of App services is the ability to create relationships between entities. A simple example of this is the Twitter-like use of following, where one user forms a relationship with another by subscribing to any tweets they post. 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 relationship where Fred is following Barney.
If you create a following relationship between two users, App Services automatically creates a virtual relationship called followers that mirrors the following relationship. In other words, if you create a relationship where Fred is following Barney, App Services automatically creates a virtual relationship where Fred is a follower of Barney. 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 relationship is a virtual relationship 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 relationship. This is wrong:
POST https://api.usergrid.com/my-org/my-app/users/barney/followers/users/fred
To create a following relationship 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 relationship structure to create connections using any "verb" that can link two entities. For example, you could use likes to denote a relationship 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 relationship between Fred and his dog Dino:
POST https://api.usergrid.com/my-org/my-app/users/fred/likes/dogs/dino
When the connection is made, you can see this relationship by making a GET call to retrieve the user named Fred:
GET https://api.usergrid.com/my-org/my-app/users/fred
This API call returns a JSON object similar to the one below. There is now a "connections" section that displays all the "likes" relationships. The connection you made to Dino is now populated. This shows that Fred Flintstone likes his dog Dino:
{
"uuid": "66be1098-9580-11e1-b37f-1231380dea5f",
"type": "user",
"name": "Fred Flintstone",
"created": 1336091450991,
"modified": 1337472944847,
"activated": true,
"email": "fred@apigee.com",
"metadata": {
"path": "/users/66be1098-9580-11e1-b37f-1231380dea5f",
"sets": {
"rolenames": "/users/66be1098-9580-11e1-b37f-1231380dea5f/rolenames",
"permissions": "/users/66be1098-9580-11e1-b37f-1231380dea5f/permissions"
},
"connections": {
"likes": "/users/66be1098-9580-11e1-b37f-1231380dea5f/likes"
},
"collections": {
"activities": "/users/66be1098-9580-11e1-b37f-1231380dea5f/activities",
"devices": "/users/66be1098-9580-11e1-b37f-1231380dea5f/devices",
"feed": "/users/66be1098-9580-11e1-b37f-1231380dea5f/feed",
"groups": "/users/66be1098-9580-11e1-b37f-1231380dea5f/groups",
"roles": "/users/66be1098-9580-11e1-b37f-1231380dea5f/roles",
"following": "/users/66be1098-9580-11e1-b37f-1231380dea5f/following",
"followers": "/users/66be1098-9580-11e1-b37f-1231380dea5f/followers"
}
},
"picture": "https://www.gravatar.com/avatar/0e827300acf163bafcc76511951fa746?d=http://apigee.com/usergrid/images/user_profile.png",
"username": "fred"
}
Note that there is no mirror relationship established. App Services only creates a mirror relationship when you create a following relationship. It does not create a mirror relationship for other verbs such as likes.
To get a list that only contains the relationships, do a GET on the connections:
GET https://api.usergrid.com/my-org/my-app/users/fred/connections
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
You can use the "me" alias in place of the current user’s uuid or username to create relationships between the current user and another entity. For example, the following request creates a relationship in which the current user likes the dog named Dino:
POST https://api.usergrid.com/my-org/my-app/users/me/likes/dogs/dino
To get a list of users who like the current user:
GET https://api.usergrid.com/my-org/my-app/users/me/connecting/likes
Note: The /users/me endpoint is accessible only if you provide an access token with the request (see Authentication and access in App Services). If you don’t provide an access token with the request, that is, you make an anonymous (or "guest") call, the system will not be able to determine which user to return as /users/me.
Other ideas for relationships include favorites, stars, knows, works_for, or owns. By following the examples above and substituting your own relationships, you can create an endless array of connections.
Deleting a connection
You can delete a relationship in a way similar to creating one. Just replace the POST method with the DELETE method. For example, you can delete the relationship between fred and barney with the following API call:
DELETE https://api.usergrid.com/my-org/my-app/users/fred/following/barney
