—Rate this article—
 

Connecting entities

When creating a connection, if you specify the collection of the entity being connected to, you can create the connection using the value of its 'name' property or its UUID.

Request syntax

To create a connection, the entity being connected to can either be specified by just its UUID, or both its collection and the value of its 'name' property.

Connect by UUID

curl -X POST https://api.usergrid.com/<org>/<app>/<connecting_collection>/<connecting_entity>/<relationship>/<connected_entity>

Connect by 'name' property

curl -X POST https://api.usergrid.com/<org>/<app>/<connecting_collection>/<connecting_entity>/<relationship>/<connected_collection>/<connected_entity>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
connecting_collection Name or UUID of the collection of the connecting entity.
connecting_entity Name or UUID of the connecting entity. If the connecting entity is a 'user' entity, the 'username' should be used rather than the 'name'
relationship Type of connection being created (e.g., likes)
connected_collection Name or UUID of the collection of the entity being connected to. This is not required if the entity being connected to is specified by its UUID.
connected_entity Name or UUID of the entity being connected to.

Example request

curl -X POST http://api.usergrid.com/your-org/your-app/users/Arthur/likes/6c56ffda-9e75-11e3-99fd-8dd1801e534c

Example Response

{
    "action" : "post",
    "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20",
    "params" : { },
    "path" : "/users/174785aa-8ea8-11e3-ae1f-eb20e5bce407/likes",
    "uri" : "https://api.usergrid.com/my-org/my-app/users/174785aa-8ea8-11e3-ae1f-eb20e5bce407/likes",
    "entities" : [ {
        "uuid" : "6c56ffda-9e75-11e3-99fd-8dd1801e534c",
        "type" : "user",
        "name" : "Arthur",
        "created" : 1393371291725,
        "modified" : 1393371291725,
        "metadata" : {
            "path" : "/users/174785aa-8ea8-11e3-ae1f-eb20e5bce407/likes/6c56ffda-9e75-11e3-99fd-8dd1801e534c"
        }
    } ],
    "timestamp" : 1393371455487,
    "duration" : 77,
    "organization" : "your-org",
    "applicationName" : "your-app"
}
		

This example uses the iOS SDK.

SDK method

To create a connection, the entity being connected to can either be specified by just its UUID, or both its collection and the value of its 'name' property.

Connect by UUID

(ApigeeClientResponse *)connectEntities: (NSString *)connecting_collection connectorID:(NSString *)connecting_entity connectionType:(NSString *)relationship connecteeID:(NSString *)connected_entity

Connect by 'name' property

(ApigeeClientResponse *)connectEntities: (NSString *)connecting_collection connectorID:(NSString *)connecting_entity connectionType:(NSString *)relationship connecteeType:(NSString *)connected_collection connecteeID:(NSString *)connected_entity

Parameters

Parameter Description
connecting_collection Name or UUID of the collection of the connecting entity.
connecting_entity Name or UUID of the connecting entity. If the connecting entity is a 'user' entity, the 'username' should be used rather than the 'name'
relationship Type of connection being created (e.g., likes)
connected_collection Name or UUID of the collection of the entity being connected to. This is not required if the entity being connected to is specified by its UUID.
connected_entity Name or UUID of the entity being connected to.

Example request

NSString *connecting_collection = @"users";
NSString *connecting_entity = @"Arthur";
NSString *relationship = @"following";
NSString *connected_collection = @"users";
NSString *connected_entity = @"Ford";

//we recommend you call ApigeeClient from your AppDelegate.
//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
//create an instance of AppDelegate
AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];

ApigeeClientResponse *response = [appDelegate.dataClient connectEntities: connecting_collection connectorID:(NSString *)connecting_entity connectionType:relationship connecteeType:connected_collection connecteeID:connected_entity];

@try {
    NSLog(@"%@", response.response);
}
@catch (NSException * e) {
    //fail
}
		

Example response

The entity that was connected to is retruned in the response:

{
    action = post;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    duration = 100;
    entities =     (
                {
            activated = 1;
            created = 1398810410556;
            metadata =             {
                collections =                 {
                    activities = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/activities";
                    devices = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/devices";
                    feed = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/feed";
                    followers = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/followers";
                    following = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/following";
                    groups = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/groups";
                    roles = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles";
                };
                path = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10";
                sets =                 {
                    permissions = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/permissions";
                    rolenames = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles";
                };
            };
            modified = 1398810410556;
            type = user;
            username = Ford;
            uuid = "5bcc47ca-cfed-11e3-8bde-a7e008061e10";
        }
    );
    organization = your-org;
    path = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes";
    timestamp = 1398810510187;
    uri = "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes";
}
		

This example uses the Android SDK.

SDK method

To create a connection, the entity being connected to can either be specified by just its UUID, or both its collection and the value of its 'name' property.

Connect by UUID

Synchronous:

ApiResponse connectEntities(String connectingEntityType,
	String connectingEntityId, String connectionType,
	String connectedEntityId)
    

Asynchronous:

ApiResponse connectEntities(String connectingEntityType,
	String connectingEntityId, String connectionType,
	String connectedEntityId, ApiResponseCallback callback)
    

Connect by 'name' property

Synchronous:

connectEntities(String connectorType,
	String connectorID, String connectionType,
	String connecteeType, String connecteeID)
    

Asynchronous:

connectEntities(String connectorType,
	String connectorID, String connectionType,
	String connecteeType,	String connecteeID,
	ApiResponseCallback callback)
    

Parameters

Parameter Description
connecting_collection Name or UUID of the collection of the connecting entity.
connecting_entity Name or UUID of the connecting entity. If the connecting entity is a 'user' entity, the 'username' should be used rather than the 'name'
relationship Type of connection being created (e.g., likes)
connected_collection Name or UUID of the collection of the entity being connected to. This is not required if the entity being connected to is specified by its UUID.
connected_entity Name or UUID of the entity being connected to.
callback Asynchronous calls only. ApiResponseCallback object to handle the asynchronous response.

Example request

			// create an instance of ApigeeClient and extract the DataClient instance
      String ORGNAME = "your-org";
      String APPNAME = "your-app";      
      ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
      ApigeeDataClient dataClient = apigeeClient.getDataClient();
 
      // connection properties
      String relationship = "likes";
      String connecting_entity = "Arthur";
      String connecting_collection = "users";
      String connected_entity = "Ford";
      String connected_collection = "users";
      
      // call connectEntitiesAsync to initiate the POST request
      client.connectEntitiesAsync(connecting_collection, connecting_entity, relationship, connected_collection, connected_entity, new ApiResponseCallback() {
      	@Override
      	public void onException(Exception e) { 
      		// Error        		
      	}
      	
      	@Override
      	public void onResponse(ApiResponse response) {
      	    try { 
      	        if (response != null) {
      	            // Success        	        	
      	        }
      	    } catch (Exception e) { //The API request returned an error
      	        	// Fail
      	    }
      	}
      });	
		

Example response

{"action":"post","application":"f34f4222-a166-11e2-a7f7-02e81adcf3d0","entities":[{"dataClient":{"accessToken":null,"apiUrl":"https://api.usergrid.com","applicationId":"your-app","clientId":null,"clientSecret":null,"currentOrganization":null,"loggedInUser":null,"organizationId":"your-org","uniqueDeviceID":"ea7c562c-684e-3074-a045-f22bc5778986"},"type":"user","uuid":"5bcc47ca-cfed-11e3-8bde-a7e008061e10","username":"Ford","created":1398810410556,"activated":true,"modified":1398810410556,"metadata":{"connecting":{"likes":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/connecting/likes"},"path":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10","sets":{"rolenames":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles","permissions":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/permissions"},"collections":{"activities":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/activities","devices":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/devices","feed":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/feed","groups":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/groups","roles":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles","following":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/following","followers":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/followers"}}}],"params":{},"path":"/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes","rawResponse":"{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes",
  "uri" : "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes",
  "entities" : [ {
    "uuid" : "5bcc47ca-cfed-11e3-8bde-a7e008061e10",
    "type" : "user",
    "created" : 1398810410556,
    "modified" : 1398810410556,
    "username" : "Ford",
    "activated" : true,
    "metadata" : {
      "connecting" : {
        "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/connecting/likes"
      },
      "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10",
      "sets" : {
        "rolenames" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles",
        "permissions" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/permissions"
      },
      "collections" : {
        "activities" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/activities",
        "devices" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/devices",
        "feed" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/feed",
        "groups" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/groups",
        "roles" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles",
        "following" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/following",
        "followers" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/followers"
      }
    }
  } ],
  "timestamp" : 1398816112120,
  "duration" : 110,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
","uri":"https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes","
		

This example uses the JavaScript (HTML5) SDK.

SDK method

Entity.connect(relationship, connected_entity, callback)

Parameters

Parameter Description
relationship Type of connection being created (e.g., likes)
connected_entity An Apigee.Entity object that models the entity being connected to.
callback Callback function to handle the async response.

Example request

// create an instance of Apigee.Client to carry your account info			
var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app',
});

// create an Entity object that models the connecting entity
var connecting_entity_options = {
    client: dataClient,
    data: {
        type:'users',
        username:'Arthur'
    }
};
var connecting_entity = new Apigee.Entity(connecting_entity_options);

// create an Entity object that models the entity being connected to
var connected_entity_options = {
    client: dataClient,
    data: {
        type:'users',
        username:'Ford'
    }
};
var connected_entity = new Apigee.Entity(connected_entity_options);

// the connection type
var relationship = 'likes';

// send the POST request
connecting_entity.connect(relationship, connected_entity, function (error, result) {

	if (error) { 
        // Error
	} else { 
		// Success
	}

});
		

Example response

Object {action: "post", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes", uri: "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes"…}
action: "post"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 123
entities: Array[1]
0: Object
activated: true
created: 1398810410556
metadata: Object
modified: 1398810410556
type: "user"
username: "Ford"
uuid: "5bcc47ca-cfed-11e3-8bde-a7e008061e10"
__proto__: Object
length: 1
__proto__: Array[0]
organization: "your-org"
params: Object
path: "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes"
timestamp: 1398817164112
uri: "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes"
__proto__: Object
		

Example request

app = Usergrid::Application.new 'https://api.usergrid.com/your-org/your-app/'
app['users/Arthur/likes/users/Ford'].post
		

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes",
  "uri" : "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes",
  "entities" : [ {
    "uuid" : "5bcc47ca-cfed-11e3-8bde-a7e008061e10",
    "type" : "user",
    "created" : 1398810410556,
    "modified" : 1398810410556,
    "username" : "Ford",
    "activated" : true,
    "metadata" : {
      "connecting" : {
        "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/connecting/likes"
      },
      "path" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10",
      "sets" : {
        "rolenames" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles",
        "permissions" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/permissions"
      },
      "collections" : {
        "activities" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/activities",
        "devices" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/devices",
        "feed" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/feed",
        "groups" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/groups",
        "roles" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/roles",
        "following" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/following",
        "followers" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/followers"
      }
    }
  } ],
  "timestamp" : 1398878233313,
  "duration" : 66,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

The example assumes use of the Node.js module.

SDK method

entity.connect(relationship, connected_entity, callback)

Parameters

Parameter Description
relationship Type of connection being created (e.g., likes)
connected_entity An Apigee.Entity object that models the entity being connected to.
callback Callback function to handle the async response.

Example request

// create an instance of Usergrid.client to carry your account info			
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app',
});

// create an entity object that models the connecting entity
var connecting_entity_options = {
    client: dataClient,
    data: {
        type:'users',
        username:'Arthur'
    }
};
var connecting_entity = new Usergrid.entity(connecting_entity_options);

// create an entity object that models the entity being connected to
var connected_entity_options = {
    client: dataClient,
    data: {
        type:'users',
        username:'Ford'
    }
};
var connected_entity = new Usergrid.entity(connected_entity_options);

// the connection type
var relationship = 'likes';

// send the POST request
connecting_entity.connect(relationship, connected_entity, function (error, result) {

	if (error) { 
        // Error
	} else { 
		// Success
	}

});
		

Example response

{ action: 'post',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: {},
  path: '/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes',
  uri: 'https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes',
  entities: 
   [ { uuid: '5bcc47ca-cfed-11e3-8bde-a7e008061e10',
       type: 'user',
       created: 1398810410556,
       modified: 1398810410556,
       username: 'Ford',
       activated: true,
       metadata: [Object] } ],
  timestamp: 1398877646279,
  duration: 135,
  organization: 'your-org',
  applicationName: 'your-app' }
		

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)