Was this helpful?

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, App Services 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, App Services automatically creates a virtual connection where Fred is a follower of Barney.

Note that there is no mirror connection established. App Services 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 a 'following' connection between fred and barney with this API call:

DELETE https://api.usergrid.com/my-org/my-app/users/fred/following/barney

Please note that the 'following' relationship is a special case that is handled differently than other entity connections. For all other entity connections, a DELETE would require the following syntax:

DELETE https://api.usergrid.com/my-org/my-app/<collection_1>/<entity_1>/<relationship>/<collection_2>/<entity_2>

So, for example, if the relationship between Fred and Barney was 'likes', the DELETE request would look like this:

DELETE https://api.usergrid.com/my-org/my-app/users/fred/likes/users/barney


How about POST multiple connections at once, for example a call for user Barney follows Fred,Sarah and Mark at once ?

Apologies for the terribly slow response. This comment got overlooked.

There currently is not a way to post multiple connections with a single call. Each connection requires a separate call to the API due to the nature of how connections are created.

How do I get the inverse relationship for a connection? I understand that ".../fred/likes/dogs/" in the example above would return "dino", but I want to be able to perform a get on something like ".../dogs/dino/liked" and get an object list back that includes fred. I tried this in the shell, but can't seem to get it working. Is this a supported feature? Is it a matter of a more advanced query?

Apologies for the slow reply, Alan. With entity connections, only the 'following' relationship automatically creates the reciprocal connection, so to implement what you are asking you must POST both the relationship and the reverse relationship when you create the connection.

So for example, you would post this to show fred likes dino:

and also post this to show dino is liked by fred:

Looks like you can't delete an entity that has a connection anymore?

`API call failed: (status: 500) org.usergrid.persistence.cassandra.ConnectedEntityRefImpl cannot be cast to org.usergrid.persistence.cassandra.ConnectionRefImpl`

Hi Brandon

This is a bug. I have opened a ticket to have it addressed. Thanks very much for reporting this.

This is great, except if you have spaces in the connection name. For example, connecting to a place called Stillwater Bar and Grill will give a null pointer error.

Hi Joe

Yes, currently referencing entities by name causes as error if there are spaces in the name. To get past this, please use the entity UUID rather than the name.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.