Relationships

Creating connections between entities

One of the most useful features of App services 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 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