Social Path (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 path in the social network between the logged in user and a target person.

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.

Both source and target must be supplied as a JSON string, using the "type" and "id" attributes as defined for the "social" parameter for the Search API.

Response Format

The response is Atom compliant. As with the Social Recommendations API and the Social Network (Graph) API, each result will also contain evidence elements.

Example

The following diagram depicts results of a path call, with one path of length 2 through Person1, and two other paths of length 3 through Person2.

 

results of a path call

An example of how the results depicted in the diagram above would be represented in the response is:

 


<atom:entry>

<atom:title>Target Person</atom:title>


<ibmss:entity_evidence type="personUserId" id="Person1"><!-- First path -->


<ibmss:association_evidence from="LoggedInUser" to="Person1" type="communityCoMembers" count="3"/>

<ibmss:association_evidence from="LoggedInUser" to="Person1" type="bookmarkedSameUrl" count="1"/>

<ibmss:association_evidence from="Person1" to="TargetPerson" type="sameManager" count="1"/>

</ibmss:entity_evidence> 

<ibmss:entity_evidence type="personUserId" id="Person2"><!-- Second path -->

<ibmss:association_evidence from="LoggedInUser" to="Person2" type="sameManager" count="1"/>

<ibmss:entity_evidence type="personUserId" id="Person3">

<ibmss:association_evidence from="Person2" to="Person3" type="taggerOf" count="1"/>

<ibmss:association_evidence from="Person3" to="TargetPerson" type="communityCoMembers" count="1"/>

</ibmss:entity_evidence>

</ibmss:entity_evidence>

<ibmss:entity_evidence type="personUserId" id="Person2"><!-- Third path -->

<ibmss:association_evidence from="LoggedInUser" to="Person2" type="sameManager" count="1"/>

<ibmss:entity_evidence type="personUserid" id="Person1"> 

<ibmss:association_evidence from="Person2" to="Person1" type="taggedBy" count="1"/>

<ibmss:association_evidence from="Person1" to="TargetPerson" type="sameManager" count="1"/>

</ibmss:entity_evidence>

</ibmss:entity_evidence>

</atom:entry>

Please note that although the above example shows how results would be depicted for paths of lengths greater than two, the maximum length is current restricted to two. This is noted above in the parameters table row relating to the maxLength parameter.

Input
Method URI Description
GET /search/atom/social/graph/path Basic
GET /search/{auth}/atom/social/graph/path 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 from which required paths start, represented using JSON.
Currently restricted to the logged-in user.
must be supplied as a JSON string, using the "type" and "id" attributes as defined for the "social" parameter for the Search API
target
string No A target person in which required paths end, represented using JSON.
must be supplied as a JSON string, using the "type" and "id" attributes as defined for the "social" parameter for the Search API
evidence
boolean Yes Specifies if evidence information is to be added to the paths.
maxLength
string Yes Specifies the maximal length allowed for paths.
connectionType
string Yes The type of connections used in calculating person to person relationships.
Currently restricted to "familiar".
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
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 social network paths from the logged in user to the person whose email is "amy@example.ibm.com" using familiarity connections:
/atom/social/graph/path?target={"type":"personEmail","id":"amy@example.ibm.com"}&connectionType=familiar