Updated March 17, 2020: Yahoo has finally implemented the new scopes and this makes a difference when you request an access token. The access token payload now returns an id_token which is a JWT containing the user details. This will beak your implementation if you update your OAuth project to use the new scopes. But don’t worry, we’ve adapted and our API is forward and backward compatible.
Has Yahoo emailed you about a required update for the Yahoo Social Directory API? Or were you browsing all the amazing APIs (jk, there’s only about 5) on developer.yahoo.com and saw this warning?
We’re informing you of a mandatory update required on your part if you wish to continue accessing profile (identity) information about Yahoo users using your service(s). Yahoo is shutting down the Yahoo Social Directory API on 2/20/2020. We have created a new UserInfo Endpoint service which you can on-board to now. The new service is only compatible with OAUTH2.0 Tokens. Please visit our Blog Post for detailed instructions to keep your service(s) from interruption.
Did you visit the “Blog Post” and find that it isn’t a blog post at all? At best, it’s a technical migration document that doesn’t answer all your questions. After reading it, I felt unsatisfied and I still had several unanswered questions about the migration.
- Will I need to create a new Yahoo App to access the new API?
- Will the new APIs support the data we are using?
- What does it mean for my application?
- How much effort will it be to migrate to the new APIs?
I was able to answer these questions for myself and I hope that by sharing some of my insights with you, you’ll be able to get a handle on what this migration means for your application.
For CloudSponge, the migration was pretty straightforward. However, there are a couple of changes that might affect your application more severely. Read on for more details.
OAuth app and scopes
Let’s resolve this easy one right away. Yes, your existing OAuth app can be used to access the new API, provided you are using OAuth2.0. Users see the same scope request on the OAuth.
I’ll point it out here because Yahoo doesn’t say this explicitly in their migration document: it looks like their app UI hasn’t been updated because new apps still need to add the old Social Directory scope in order to access the new UserInfo endpoint. It looks like the old scopes map to the new ones as below:
|
Old “Profiles (Social Directory)” Scope |
New UserInfo Scope |
Read Publicsdps-r (basic profile read) |
profile |
Read/Write Public and Privatesdpp-r (extended profile read) |
email |
I’ll be watching and waiting for a day when Yahoo’s App interface supports adding the “Read Public and Private”. CloudSponge doesn’t ever write the user’s profile data but we do need the email address, which falls into the “private” or “extended” profile scope. Until then, I’ll keep using the same OAuth App.
The scopes are equivalent with a couple of exceptions (see missing data below). So, if you are accessing the profiles API to get the user’s name and email address, then the same Yahoo app can be used to get the user’s name and email address from the UserInfo endpoint. So far, so good!
So what is different?
Well, read on and I’ll describe what has changed.
Response format
The UserInfo response payload now only responds with JSON format. This will likely be the biggest change if you are currently using the XML response format. Fortunately, JSON is a very well supported format with [plenty of libraries] for your application to adopt to do the decoding for you.
The payload format has also been flattened. The UserInfo endpoint returns a single object that holds the user’s properties. Now you can simplify the property accessors in your code.
Some minor changes
But don’t just try to access the same profile attributes! Attribute names now use snake_case instead of camelCase. For example, givenName is still present in the data, but it’s now called given_name. OK, no big deal.
Birthday now only includes the birth year. No month or date. If you are using this information, your age approximations will be +/- 6 months.
If your application is using the profile API for email addresses, no problem! Instead of hunting through an array of email addresses, the new UserInfo endpoint returns a single email field. Simple.
The same is true for the user’s phone number. It’s now a single phone_number field.
The profile API accepts the access_token as a query string parameter. The UserInfo endpoint does not. So you’ll need to move the access token to the “Authorization: Bearer” header. This is pretty standard for OAuth endpoints. But this fact might see some unexpected 401 errors on the UserInfo endpoint.
You weren’t using that, were you?
Here’s some bad news, potentially.
Most of the same data fields are returned on the UserInfo endpoint. However, there are some exceptions. If you are expecting any of these fields, you’ll need to adjust because they are no longer supported. There are 18 deprecated fields in total; here are a few of them:
- addresses
- birthdate
- displayAge
- memberSince
- profileUrl
- timeZone
- See the rest at the end of Yahoo’s article.
What’s next?
I hope this article helps you to plan your migration effort. There are still a few months to get things squared away but it’s a good idea to tackle this sooner than later.
For CloudSponge customers who happen to be reading this article, your migration is already complete.
