Entity connections

You can create connections between entities, then use those connections to more easily retrieve entities with the API BaaS API.

A connection represents a relationship between entities, often in a one-to-many structure. For example, one user "following" another can be represented as a connection. And when one user is followed by many others, you can use a connection (such as "followedBy") to get entities for all of the following users. This GET could retrieve an array of the users following Jennie:

GET /users/jennie/followedBy

The preceding example assumes that you've created connections between Jennie and her followers:

POST /users/jennie/followedBy/users/gladys
POST /users/jennie/followedBy/users/darrin

Choosing verbs to connect with

API BaaS connections are simple in practice, but can be a little hard to grasp at first. That's partly because the word you use to connect entities can be any verb you like. There's no predefined list of keywords. Words like "follows" and "likes" are common examples for creating relationships between users. But you might use "contains" for food items associated with a menu or "manages" to connect a manager (user) with their direct reports (users).

For example, imagine you have a restaurant review app with a user entity type and a review entity type. And imagine that a single user could write many reviews during their time as a user. You'd want to be able to get all the reviews written by a user -- in SQL terms, reviews WHERE user=userName.

If you have a user Jennie and three existing reviews, you could Jennie with her reviews with the verb wrote -- like this:

POST /users/jennie/wrote/review1
POST /users/jennie/wrote/review2
POST /users/jennie/wrote/review3

Then you could use the following to get all three reviews by Jennie:

GET /users/jennie/wrote

The response would include an array of the review entities for review1review2review2.

Connecting entities when you create them

The preceding example works if both the jennie entity and review entities already exist and you're connecting them. Imagine instead that you wanted to connect Jennie with her reviews when she POSTs the review -- in other words, when your code creates the review entity.

The following example creates Jennie’s review and at the same time connects her as the person who wrote it. From this example, API BaaS knows that you're connecting on entity type with another. It knows your entities (users and reviews) and it assumes the word between is a connecting verb. And it accepts the JSON body as the new entity to create in the data store.

(For easier reading, this example contains spaces you wouldn’t be able to include.)

POST http://<baas_host_name>/my_org/my_app/users/jennie/wrote/reviews { 
    "title" : "Tempted to climb in myself.", 
    "body" : "I mean, who doesn't love a bouncy castle? The kids love it!", 
    "rating" : 3, 
    "authorName" : "Jennie", 
    "authorImage" : "http://<path_to_image>.png", 
    "productName" : "Magic Castle Bounce House Inflatable Bouncer", 
    "productImage" : "http://<path_to_image>.jpg" 

When reading the data, you’d retrieve all of Jennie's reviews with a URL like this:

GET http://<baas_host_name>/my_org/my_app/users/jennie/wrote

The response would look something like the following. Notice that it includes an entities array with Jennie's review. (We're assuming there's only one review here -- if there were three, the other two would also be in the array). Your client code could iterate through the entities array to display them for Jennie. This example also shows the metadata about connections Jennie is a part of.

    "action" : "get", 
    "application" : "<app_uuid>", 
    "params" : { }, 
    "path" : "/users/<user_uuid>/wrote", 
    "uri" : "https://<baas_host_name>/my_org/my_app/users/<user_uuid>/wrote", 
    "entities" : [ {
        "uuid" : "<review_uuid>", 
        "type" : "review", 
        "created" : 1395410364673, 
        "modified" : 1395410364673, 
        "authorName" : "Jennie", 
        "authorImage" : "http://<path_to_image>.png", 
        "authorUUID" : "<user_uuid>", 
        "body" : "I mean, who doesn't love a bouncy castle? Kids love it!", 
        "metadata" : { 
            "connecting" : {
                "wrote" : "/users/<user_uuid>/wrote/<review_uuid>/connecting/wrote" 
            "path" : "/users/<user_uuid>/wrote/<review_uuid>", 
        "productImage" : "http://<path_to_image>.jpg", 
        "productName" : "Magic Castle Bounce House Inflatable Bouncer", 
        "productUUID" : "<product_uuid>", 
        "rating" : 3, 
        "title" : "Tempted to climb in myself." 
    } ], 
    "timestamp" : 1395777037697, 
    "duration" : 19, 
    "organization" : "my_org", 
    "applicationName" : "my_app" 

To retrieve a particular review written by Jennie, you could use something like the following:

GET http://<baas_host_name>/my_org/my_app/users/jennie/wrote/reviews/<review_uuid>