Was this Helpful?

Viewing all of an entities connections

To see all of the connection types associated with an entity, simply retrieve the entity.

All of the connection types the entity has made to other entities will appear in the metadata.connections property.

All of the connection types that other entities have made to the entity will appear in the metadata.connecting property.

For user entities, following/followers connections can be accessed by sending a GET request to the URL in the collections.following and collections.followers properties.

Retrieve connected entities by connection type

To get a list of entities a specified entity has connected to with a specific connection type, do the following:

Request syntax

curl -X GET https://api.usergrid.com/<org>/<app>/<collection>/<entity>/<relationship>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
collection Name or UUID of the collection of the entity you want to retrieve the connections of.
entity Name or UUID of the entity whose connections you want to retrieve
relationship The connection type you want to retrieve the entities for. For example, 'likes' would return a list of all entities that have the 'likes' connection with the specified entity.

Example request

curl -X GET https://api.usergrid.com/your-org/your-app/users/Arthur/likes

Example response

Notice that the entities are returned as a JSON array in the entities property.

{
  "action" : "get",
  "application" : "dk88fh4r-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" : 1398884631067,
  "duration" : 41,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

SDK method

(ApigeeClientResponse *)getEntityConnections: (NSString *)collection connectorID:(NSString *)entity connectionType:(NSString *)relationship query:(ApigeeQuery *)query

Parameters

Parameter Description
collection Name or UUID of the collection the entity belongs to.
entity Name or UUID of the entity whose connections you want to retrieve.
relationship The connection type you want to retrieve the entities for. For example, 'likes' would return a list of all entities that have the 'likes' connection with the specified entity.
query An optional ApigeeQuery object for refining the response set.

Example request

NSString *collection = @"users";
NSString *entity = @"Arthur";
NSString *relationship = @"connections";

//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 getEntityConnections:collection connectorID:entity connectionType:relationship query:nil];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

{
  action = get;
  application = "dk88fh4r-a166-11e2-a7f7-02e81adcf3d0";
  applicationName = your-app;
  duration = 27;
  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";
            };
            connecting =                 {
                likes = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/connecting/likes";
            };
            connections =                 {
                friends = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/friends";
                likes = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/likes";
            };
            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;
  params =     {
  };
  path = "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes";
  timestamp = 1398894604563;
  uri = "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes";
}
		

SDK method

Synchronous

queryEntityConnectionsAsync(String collection, String entity, 
	String relationship, String query)
		

Asynchronous

queryEntityConnectionsAsync(String collection, String entity, 
	String relationship, String query, QueryResultsCallback callback)
		

Parameters

Parameter Description
collection Name or UUID of the collection the entity belongs to.
entity Name or UUID of the entity whose connections you want to retrieve.
relationship The connection type you want to retrieve the entities for. For example, 'likes' would return a list of all entities that have the 'likes' connection with the specified entity.
query An optional query string for refining the response set.
callback Asynchronous requests only. A QueryResultsCallback for handling the async response.

Example request

String relationship = "likes";
String entity = "Arthur";
String collection = "users";
String ql = "";

dataClient.queryEntityConnectionsAsync(collection, entity, relationship, query, new QueryResultsCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
	}

	@Override
	public void onResponse(Query response) {
	    try { 
	        if (response != null) {
	            // Success        	
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    }
	}

	@Override
	public void onQueryResults(Query query) {
		//Success
	}
});	
		

Example response

The following is the raw response extracted from the returned Query object.

{
  "action" : "get",
  "application" : "dk88fh4r-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"
      },
      "connections" : {
        "friends" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/friends",
        "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/likes"
      },
      "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" : 1398896918188,
  "duration" : 39,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

SDK method

Entity.getConnections(relationship, callback)

Parameters

Parameter Description
relationship The connection type you want to retrieve the entities for. For example, 'likes' would return a list of all entities that have the 'likes' connection with the specified entity.
callback A callback function for handling the async response.

Example request

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

// create an Apigee.Entity object that models the entity to retrieve connections for
var options = {
    client: dataClient,
    data: {
        type:'users',
        username:'Arthur'
    }
};

var entity = new Apigee.Entity(options);

// the connection type you want to retrieve
var relationship = 'likes';

// initiate the GET request
entity.getConnections(relationship, function (error, result) {

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

});
		

Example response

Object {action: "get", application: "dk88fh4r-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: "get"
application: "dk88fh4r-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 29
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: 1398899444549
uri: "https://api.usergrid.com/your-org/your-app/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes"
		

Example request

usergrid_api = 'https://api.usergrid.com/'
organization = 'your-org'
application = 'your-app'

client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
response = client['users/Arthur/likes'].get

rescue
	#fail
end
		

Example response

{
  "action" : "get",
  "application" : "dk88fh4r-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"
      },
      "connections" : {
        "friends" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/friends",
        "likes" : "/users/58606d0a-cfed-11e3-a694-dbf5228024a7/likes/5bcc47ca-cfed-11e3-8bde-a7e008061e10/likes"
      },
      "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" : 1398900300138,
  "duration" : 26,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

SDK method

Entity.getConnections(relationship, callback)

Parameters

Parameter Description
relationship The connection type you want to retrieve the entities for. For example, 'likes' would return a list of all entities that have the 'likes' connection with the specified entity.
callback A callback function for handling the async response.

Example request

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

// create an Usergrid.Entity object that models the entity to retrieve connections for
var options = {
    client: dataClient,
    data: {
        type:'users',
        username:'Arthur'
    }
};

var entity = new Usergrid.entity(options);

// the connection type you want to retrieve
var relationship = 'likes';

// initiate the GET request
entity.getConnections(relationship, function (error, result) {

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

});
		

Example response

{ action: 'get',
  application: 'dk88fh4r-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: 1398899763810,
  duration: 20,
  organization: 'your-org',
  applicationName: 'your-app' }
		

Retrieve all connected entities

To get a list of all the entities a specified entity has connected to, use the same method as shown above in Retrieve connected entities by connection type, and replace set the relationship to connections.

All of the entities that have made a connection of that type to the specified entity will be returned in the entities property of the response.

Retrieve all connecting entities by type

To get a list of all the entities that have created a connection of a specific type to a specified entity, use the same method as shown above in Retrieve connected entities by connection type, and replace set the relationship to connecting/<relationship>.

All of the entities that have made a connection to the specified entity will be returned in the entities property of the response.

Retrieve all connecting entities

To get a list of all the entities that have connected to a specified entity, use the same method as shown above in Retrieve connected entities by connection type, and replace set the relationship to connecting.

All of the entities that have made a connection to the specified entity will be returned in the entities property of the response.

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?)