Chapter 2. Social Directory API
Introduction to Social Directory API
The Social Directory API provides profile (identity) and connection
(relationship) information about Yahoo! users. A profile is a collection
of user provided information that is descriptive of the user, such as the
user's name, gender, location, photo, and relationship status. The
connections of a user identify other users who might be friends and
business associates. To form a connection, both users must confirm the
relationship. For example, if Joe wants to add Jane to his list of
connections, he asks that she be added and she has to approve. The
benefits of connecting include more information sharing between users on
Yahoo! properties as well as on 3rd-party sites and applications.
Certain information will be
displayed only if certain permissions have been met in the form of a
documented relationship between the viewer and the profile owner. In
addition, the profile owner decides what user information will be made
publicly available, shared to connections and 3rd party applications, or
shared only to connections.
The Social Directory API contains URIs to obtain different sets of
data from a user's profile. The following types of cards are
distinguished by the packages of data exposed.
Tinyusercards contain only minimal profile data. Use the Tinyusercard Profile URI to get
a profile owner's Tinyusercard profile.
Usercards contain the user's Core Profile information. Use the
Usercard Profile URI to get a
profile owner's Usercard profile.
Extended Usercards are Core Usercards that pull in Profile data
or contain permissioned information that requires a relationship
lookup. Use the Profile URI to get a
profile owner's profile.
A user's connections are a subset of their contacts. Connections
are two-way, signifying that both users have confirmed their desire to
be mutually connected in order to share a potentially higher degree of
information between each other. Although the Connections API provides
access to these confirmed associations, connections can only be created
by Yahoo! users.
Getting access to your connections is key to effectively using the
Social Platform APIs. In particular, the Connections API provides you
with the endpoints to find your connections' usercards or tinyusercards.
This in turn provides you with their GUID and URI, information which you
can subsequently use to develop a rich social network.
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.
Matrix Parameters for the Social Directory API
Matrix parameters enable the application to retrieve part of a
collection when calling an HTTP GET operation. A
matrix parameter can follow any collection path segment in a URI. For
more details about how to use the matrix parameters, refer to Paging a Collection.
The table below lists the matrix parameters with their
corresponding data types.
Table 2.1.
| Parameter |
Data |
Description |
start
|
integer |
The first item in the collection to be returned by GET. The default is 0.
|
count
|
integer |
The number of items in the collection to be returned by GET. The default is 10.
|
The example below uses the matrix parameters
start and count to return the
first twenty connections of a user. Note that a matrix parameter is
preceded by a semicolon.
http://social.yahooapis.com/v1/user/6677/connections;start=0;count=20
In the Social Directory API, you can also assign the matrix
parameter count with the value of the constant
max. The constant max is the
largest possible number of elements from a collection that can be
returned by the specified Social Directory API.
This example returns the maximum number of connections possible
from the Connections API.
http://social.yahooapis.com/v1/user/6677/connections;count=max
Chapter 2. Social Directory API
Introduction to Social Directory API
The Social Directory API provides profile (identity) and connection (relationship) information about Yahoo! users. A profile is a collection of user provided information that is descriptive of the user, such as the user's name, gender, location, photo, and relationship status. The connections of a user identify other users who might be friends and business associates. To form a connection, both users must confirm the relationship. For example, if Joe wants to add Jane to his list of connections, he asks that she be added and she has to approve. The benefits of connecting include more information sharing between users on Yahoo! properties as well as on 3rd-party sites and applications.
Profiles
Certain information will be displayed only if certain permissions have been met in the form of a documented relationship between the viewer and the profile owner. In addition, the profile owner decides what user information will be made publicly available, shared to connections and 3rd party applications, or shared only to connections.
The Social Directory API contains URIs to obtain different sets of data from a user's profile. The following types of cards are distinguished by the packages of data exposed.
Tinyusercards
Tinyusercards contain only minimal profile data. Use the Tinyusercard Profile URI to get a profile owner's Tinyusercard profile.
Usercards
Usercards contain the user's Core Profile information. Use the Usercard Profile URI to get a profile owner's Usercard profile.
Extended User Cards
Extended Usercards are Core Usercards that pull in Profile data or contain permissioned information that requires a relationship lookup. Use the Profile URI to get a profile owner's profile.
Connections
A user's connections are a subset of their contacts. Connections are two-way, signifying that both users have confirmed their desire to be mutually connected in order to share a potentially higher degree of information between each other. Although the Connections API provides access to these confirmed associations, connections can only be created by Yahoo! users.
Getting access to your connections is key to effectively using the Social Platform APIs. In particular, the Connections API provides you with the endpoints to find your connections' usercards or tinyusercards. This in turn provides you with their GUID and URI, information which you can subsequently use to develop a rich social network.
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.
Matrix Parameters for the Social Directory API
Matrix parameters enable the application to retrieve part of a collection when calling an HTTP
GEToperation. A matrix parameter can follow any collection path segment in a URI. For more details about how to use the matrix parameters, refer to Paging a Collection.The table below lists the matrix parameters with their corresponding data types.
Table 2.1.
startGET. The default is 0.countGET. The default is 10.The example below uses the matrix parameters
startandcountto return the first twenty connections of a user. Note that a matrix parameter is preceded by a semicolon.http://social.yahooapis.com/v1/user/6677/connections;start=0;count=20In the Social Directory API, you can also assign the matrix parameter
countwith the value of the constantmax. The constantmaxis the largest possible number of elements from a collection that can be returned by the specified Social Directory API.This example returns the maximum number of connections possible from the Connections API.
http://social.yahooapis.com/v1/user/6677/connections;count=max