developer

SocDir (Social Directory Web Service) - EOL date is June 30, 2020



EOL Plan

The existing social directory APIs are being end-of-lifed (EOL). This page provides a roadmap and the steps needed to enable your service to continue to operate properly.
Deprecation of attributes in Legacy Socialdirectory API will start between March 15th to March 31th, 2020. Legacy Socialdirectory APIs will continue to serve until June 30, 2020, but the returned data may be different based on the attributes that are no longer being supported.

Legacy Socialdirectory API will be completely shut down on June 30, 2020. Developers are requested to use the new UserInfo API.
  1. Apps that have used Legacy Socialdirectory API in the last 90 days can continue to use them until June 30th, 2020.
  2. Apps that have not used any of Legacy Socialdirectory API in the last 90 days will be unable to use them starting on March 31th, 2020. The existing consumer key can be used against the new UserInfo API.
  3. New Apps created after March 31th, 2020 will be unable to use Legacy Socialdirectory API and must be using the new UserInfo API .

What is the Social Directory API and what does it currently provide?

The Social Directory API provides profile (identity) 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 and photo. The Social Directory API contains URIs to obtain different sets of data from a user's profile.

SocialDirectory Endpoint:
https://social.yahooapis.com/v1/user/abcdef123/profile

Request:
GET https://social.yahooapis.com/v1/user/abcdef123/profile?format=json
Authorization: Bearer <Bearer Token>

Sample Response:
{
profile: {
  guid: "DKZCPIB7ZJZTWRC5A3W4Y5N3M4",
  addresses: [ {
    city: "",
    country: "US",
    current: true,
    id: 1,
    postalCode: "",
    state: "",
    street: "",
    type: "HOME"
  } ],
  ageCategory: "A", 
  birthYear: "XXXX",
  birthdate: "XX/XX",
  created: "2019-04-30T20:48:14Z",
  displayAge: "XX",
  emails: [ {
    handle: "jasonsmith@gmail.com",
    id: 10,
    type: "HOME"
  }, {
    handle: "jasonsmith@yahoo.com",
    id: 1,
    primary: true,
    type: "HOME"
  } ],
  familyName: "Smith",
  gender: "M",
  givenName: "Jason",
  image: {
    height: 192,
    imageUrl: "https://ct.yimg.com/cy/1768/39361574426_98028a_192sq.jpg",
    size: "192x192",
    width: 192
  },
  intl: "us",
  jurisdiction: "us",
  lang: "en-US",
  memberSince: "2014-12-18T04:36:14Z",
  migrationSource: 1,
  nickname: "Jason",
  notStored: true,
  nux: "0",
  phones: [ {
    id: 10,
    number: "1-610XXXXXXX",
    type: "MOBILE",
    verified: true
  } ],
  profileMode: "PUBLIC",
  profileStatus: "ACTIVE",
  profileUrl: "http://profile.yahoo.com/DKZCPIB7ZJZTWRC5A3W4Y5N3M4",
  timeZone: "America/Los_Angeles",
  isConnected: false,
  profileHidden: false,
  profilePermission: "PRIVATE",
  uri:"https://social.yahooapis.com/v1/user/DKZCPIB7ZJZTWRC5A3W4Y5N3M4/profile",
  cache: true
  }
}
This Legacy Profile API supported both OAUTH 1.0 and OAUTH2.0 Tokens. It also had both JSON and XML mode.

What is this new service you speak of?

The new service is the UserInfo Endpoint which is OAuth 2.0 protected. To obtain profile information about the user, you can use the access token (which your application receives via the OAuth2.0 authentication).
To determine the scope of information the client must include the “openid profile scope” in your authentication request.

UserInfo Endpoint:
https://api.login.yahoo.com/openid/v1/userinfo

Request:
GET https://api.login.yahoo.com/openid/v1/userinfo
Authorization: Bearer <Bearer Token>

Sample Response:
{
  sub: "JEF4XR2CT55JPVEBVD7ZVT6A3A",
  name: "Jasmine Smith",
  given_name: "Jasmine",
  family_name: "Smith",
  locale: "en-US",
  email: "yqa_functest_15572415322065371@yahoo.com",
  email_verified: true,
  birthdate: "1972",
  profile_images: {
   image32: "https://ct.yimg.com/cy/1768/39361574426_98028a_32sq.jpg",
   image64: "https://ct.yimg.com/cy/1768/39361574426_98028a_64sq.jpg",
   image128: "https://ct.yimg.com/cy/1768/39361574426_98028a_128sq.jpg",
   image192: "https://ct.yimg.com/cy/1768/39361574426_98028a_192sq.jpg"
  },
  preferred_username: "yqa_functest_15572415322065371@yahoo.com",
  nickname: "Jasmine",
  picture: "https://ct.yimg.com/cy/1768/39361574426_98028a_192sq.jpg"
}
This new OpenId Connect UserInfo API supports only OAUTH2.0 Tokens. This API is not backward compatible to the legacy API. It supports only JSON format in response.

Different scopes supported:
1) Read Public Basic ( Deprecated )
2) Read Public Extended ( Deprecated )
3) Profile ( New )
4) Email ( New )

The deprecated of scopes won't affect the existing apps, but the returned data may be different based on the attributes that are no longer being supported. New Apps must use either 'Profile' , 'Email' or both as their scopes to obtain user data. 

Profile Attributes returned for Deprecated Scopes:
Scope Attribute Attribute Details
Read Public Basic ( Deprecated ) sub SubjectId (User’s Unique Identifier)
name User’s full name
given_name User’s first name
family_name User’s family name
locale User’s language
Read Public Extended ( Deprecated ) sub SubjectId (User’s Unique Identifier)
name User’s full name
given_name User’s first name
family_name User’s family name
locale User’s language
email User’s preferred email
email_verified Is the User’s email verified by user
birthdate Birth Year of User
profile_images Contains URIs for the profile images of the user. ( image32*32, image64*64, image128*128, image192*192)
picture Contains URI for the profile image of user (192*192)
preferred_username Preferred username of the User
nickname User’s nickname

Profile Attributes returned for New Scopes:
Scope Attribute Attribute Details
Profile ( New scope ) sub SubjectId (User’s Unique Identifier)
name User’s full name
given_name User’s first name
family_name User’s family name
locale User’s language
nickname User’s nickname
gender User’s gender
middle_name User’s middle name
profile_images Contains URIs for the profile images of the user. ( image32*32, image64*64, image128*128, image192*192)
Email ( New scope ) email User’s preferred email
email_verified Is the User’s email verified by user

Compatibility between previous Social Directory profile api attributes and new User Info attributes?
Social Directory Profile Attribute New User Info Attribute Attribute Description
guid sub User’s Unique Identifier
givenName given_name User’s first name
familyName family_name User’s family name
lang locale User’s language
emails (Array of user’s emails) email User’s preferred email. (An array of emails is replaced with one preferred email of the user)
birthYear birthdate Birth Year of User. NOTE: birthdate is only returned for old consumer keys which had the "Read Public Extended" deprecated scope
image profile_images New attribute contains the image32, image64, image128, image192 profile image url.
nickname nickname User’s nickname
gender gender User’s gender

List of Attributes Deprecated in Social Directory Profile Api:
1) addresses
2) ageCategory
3) birthdate
4) cache
5) displayAge
6) intl
7) isConnected
8) jurisdiction
9) memberSince
10) notStored
11) nux
12) profileUrl
13) profileMode
14) profileStatus
15) profileHidden
16) profilePermission
17) timeZone
18) uri
19) phones
NOTE: Profile Info response in XML format is deprecated.

List of New Attributes added to User Info Endpoint
1) name
2) email_verified
3) preferred_username

Where can I get all of the documentation?

How to create an app?
https://developer.yahoo.com/apps/create/

Yahoo Oauth 2.0 Documentation:
https://developer.yahoo.com/oauth2/guide/

Yahoo OpenId Connect Documentation:
https://developer.yahoo.com/oauth2/guide/openid_connect/

The OpenId discovery document:
https://api.login.yahoo.com/.well-known/openid-configuration