Connections

Description

Connections returns the user's connections. A user's connections, which are mutually confirmed relationships, allow for a higher degree of shared information. The Connections API provides access to these confirmed associations.

Note

The Connections API is being deprecated. To access connections, use the Relationships API, which provides access ti one-way (contacts) and two-way (connections) relationships. For more information, see Relationships.

URI

GET returns a collection of connections for the profile owner specified by {guid}.

http://social.yahooapis.com/v1/user/{guid}/connections

HTTP Operations Supported

  • GET

Query Parameters Supported

  • callback
  • format
  • handle
  • view
  • .imgssl

The view query parameter can have the following values:

  • contactcard - Includes the contactcard profile for each connection.
  • idcard - Includes the IDcard profile for each connection.
  • profile - Includes the extended profile for each connection.
  • tinyusercard - Includes the tinyusercard profile for each connection.
  • usercard - Includes the usercard profile for each connection.

Matrix Parameters Supported

  • start
  • count
  • mutual
  • out
  • sort

Scopes Required

  • GET: Read (Shared) Yahoo! Profiles

Elements of the Connections Object

Element JSON Data Type XML Schema Data Type Description
connection array of Connection Objects Zero or more Connection Objects Collection of Connection Objects.
contactid number positiveInteger An ID corresponding to this connection (every connection must have an entry in address book).
count number nonNegativeInteger Number of connections returned.
created string dateTime Date resource was created.
guid string string GUID of the profile owner.
start number nonNegativeInteger Index of first connection returned.
total number nonNegativeInteger Total number of connections.
updated string dateTime Date resource was last modified.
uri string anyURI Reference to actual resource.

JSON Syntax for Connections Object

XML Syntax for Connections Object

Example JSON Response Body for GET All Connections

Example XML Response Body for GET All Connections

Filtering

Filters can only be used when calling the HTTP GET method of the Connections URI. If you call GET without a filter, you get a response including all of the connections from the authenticated user's connections list.

The two types of filtering are search and display. Search filtering allows you to select a subset of the authenticated user's contacts. Display filtering allows you to select fields from the returned Connection Objects. Search and display filtering can be used independently or conjunctively.

Search Filtering

Using search filters, you can get Connection Objects in the response that match certain criteria. The handle query parameter allows you to select connections by specifying one or more Yahoo! IDs or email addresses.

The mutual matrix parameter allows you to get the mutual connections of the profile owner and the user specified by a GUID. If the profile owner and the user specified by the GUID have no mutual connections, an empty response is returned.

The following authorized users can view the returned mutual connections:

  • The profile owner specified by {guid1} in the URL below:

    /v1/user/{guid1}/connections;mutual={guid2}

  • The user specified by {guid2} in the URL below:

    /v1/user/{guid1}/connections;mutual={guid2}

  • Mutual connections of both the profile owner ({guid1}) and the user ({guid2}) in the URL below:

    /v1/user/{guid1}/connections;mutual={guid2}

Syntax

Search filters are appended to the URI for the Connections API.

A URI with a search filter that uses the handle query parameter has the following syntax:

http://social.yahooapis.com/v1/user/{guid}/connections?handle={value}

The value assigned to handle can either be a list of email addresses or YIDs.

The URI with a search filter that uses the mutual matrix parameter has the following syntax:

http://social.yahooapis.com/v1/user/{guid}/connections;mutual={guid-of-connection}

Search Filter Examples

To find a connection with an email address, use the handle query parameter with {email-address}.

http://social.yahooapis.com/v1/user/{guid}/connections?handle={email-address}

To find the mutual connections of the authorized user and one of the user's connections, use the mutual matrix parameter with the connection's GUID ( {guid2}).

http://social.yahooapis.com/v1/user/{guid1}/connections;mutual={guid2}

Display Filtering

Display filters are used with the HTTP GET method to obtain a subset of the fields for each returned Connection Object in the response. The out matrix parameter specifies the fields to be returned for each Connection Object.

Syntax

Display filters are appended to the URI of the Connections API. The GUID of the user is represented by {guid}, and the profile to be returned with each connection is {profile-type}. The fields of the profile that are returned are represented by {field1}, {field2}, and {field3}.

/v1/user/{guid}/connections;out={field1},{field2},{field3}?view={profile-type}

The {profile-type} can have any of the following values:

  • contactcard
  • idcard
  • profile
  • tinyusercard
  • usercard

The pair out and fields define the fields of the Connection Objects that will be returned in the response. The key fields can be one or more fields of the Connection Object, with each field being separated by a comma.

The fields key may consist of the following:

  • A comma-separated list of Field Types to return. If the fields parameter is omitted, all fields are returned.

  • all - include all fields. The default is to include all fields if no fields key is given.

Display Filter Examples

Return only the name, nickname, and phone fields of the extended profile for each Connection Object in the response:

/v1/user/{guid}/connections;out=name,nickname,phone?view=profile

Return the image, nickname, and status fields of the usercard profile for each Connection Object in the response:

/v1/user/{guid}/connections;out=image,nickname,status?view=usercard

Sorting

The returned connections can be sorted based on certain criteria by using the sort key, which is appended to the URL of the Connections API as a matrix parameter.

The sort key may be assigned the following values:

  • birthdate - sorts connections by birthday relative to current date
  • created - sorts in descending time of when connections were created
  • nickname - sort in ascending order by nickname
  • random - returns connections in random order

To sort by nickname, the view query parameter must be used with the value usercard or tinyusercard.

Sorting Examples

This URL returns the connections in descending time of when the connections were created:

http://social.yahooapis.com/v1/user/{guid1}/connections;sort=created

This URL returns the connections in ascending order by each connection's nickname:

http://social.yahooapis.com/v1/user/{guid1}/connections;sort=created?view=usercard

Table of Contents