Social Network (Graph) API
Added by IBM contributorIBM | Edited by Claudia R Elbourn on June 30, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

This document describes the API call which enables retrieval of a set of persons with whom the 'source' person in the query has associations. For example, the implicit social network of a person, or a list of person to recommend the user connect with.

Parameters

 

The order of the parameters in the requests do not matter. The parameter names are case-sensitive; they must be entered in the format documented. Any unknown or unsupported parameters submitted as part of a request will be ignored.

The request should be a standard HTTP GET command. The URL is formed by combining the search server's host name, port and path; as well as a collection of name-value pairs (input parameters) separated by & characters. Any parameter value must be URL-escaped.

Source should be supplied as a JSON string, using the "type" and "id" attributes as defined for the "social" parameter in Search API.

Response Format

The following graph depicts an example involving different types of associations:

 

example involving different types of associations

As with the Social Recommendations API, each result will also contain evidence elements. In this case, however, the evidence elements correspond to the associations. In the example shown in the graph above, the first related person has two associations with the person in the query: they have the same manager, and there are 3 communities in which both are members. The second related person also has two associations with the person in the query: there are 4 communities in which both are members, and there are two URLs that both of them bookmarked. An example of how this would be represented in the response is:

 

<atom:entry>

<atom:title>Related Person Name 1</atom:title>


<atom:id>RelatedPerson1</atom:id>


<ibmss:association_evidence from="SourcePersonId" to="RelatedPerson1" type="sameManager" count="1"/>

<ibmss:association_evidence from="SourcePersonId" to="RelatedPerson1" type="communityCoMembers" count="3"/>

</atom:entry>


<atom:entry>


<atom:title>Related Person Name 2</atom:title>


<atom:id>RelatedPerson2</atom:id>


<ibmss:association_evidence from="SourcePersonId" to="RelatedPerson2" type="communityCoMembers" count="4"/>

<ibmss:association_evidence from="SourcePersonId" to="RelatedPerson2" type="bookmarkedSameUrl" count="2"/>



</atom:entry>

 

Input
Method URI Description
GET /search/atom/social/graph/list Basic
GET /search/{auth}/atom/social/graph/list OAuth
Name Type Optional Description
auth
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
Name Type Optional Description
source
string Yes The source person, represented using JSON. Source should be supplied as a JSON string, using the "type" and "id" attributes as defined for the "social" parameter in Search API
Optional parameter. Restricted in Connections Search 4.0 this to the logged-in user.
connectionType
string Yes The type of connections used in calculating person to person relationships.
Optional parameter. Restricted in Connections Search 4.0 to "familiar".
evidence
boolean Yes Specifies if evidence information is to be added to the paths.
page
int Yes Page number.
Negative values are not allowed.
pageSize
int Yes Number of results desired for a single request.
Negative values are not allowed.
type
enumerated Yes The type of results you want returned. This filters the set of persons that would be returned as per the argument specified.
Values:
1. 'buildNetwork' - (default) used by 'Do You Know' widget - filters out people I've already added as a colleague, or choose not to add.
2. 'getNetwork' - retreives the user's social network (familiarity based).
Authorized values:
  • buildNetwork, getNetwork
Name Type Optional Description
Authorization
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(twatson@us.ibm.com:password).
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
Output
Content Type: application/atom+xml
Code Description
401
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
Examples
An example of a call for finding recommendations for the currently logged in user to build his/her network using familiarity connections (aka Do You Know query)
/search/atom/social/graph/list?type=buildNetwork&connectionType=familiar

retrieves the user's social network (familiarity based).
/search/atom/social/graph/list?type=getNetwork