Tuesday, November 15, 2011

how to yahoo Contact Reader Using ASP.NET


Introduction

Mail contact reader have become an exciting feature as new social sites are being introduced or email-campaign becomes a key success factor for online business. I have worked on several projects where app facilitates email contact reading from user’s personal mailing account. Most of the users use free mailing services like Gmail/Hotmail/AOL/Yahoo and the list goes on. Most of the time, I used third party solutions (that saves lots of my time) and those work pretty well. But those solutions I used are not easy to customize according to my needs. So this time, I have decided to find myself a stable solution and I started with a very popular mail service Yahoo!. This article will be helpful for those people who are working with contact reader app and for those who are interested in working with Yahoo! API.

Yahoo! API

The Yahoo! Developer Network (YDN) is Yahoo!'s center for developer resource. YDN contains tools/utilities/gadgets/API docs and samples for developers.You can start using the resources provided by signing yourself for an API key and you are ready to go.

Authentication and Authorization with Yahoo!

Yahoo! offers 3 ways to connect with their services, the first is OpenID to authenticate users, the second one is OAuth to control access to protected data and the third one is OpenID-OAuth Hybrid Protocol, which combines OpenID authentication with OAuth authorization in a single interface. I found OAuth is most convincing and will stick to it for this article. If you want to know more about other 2 authentication models, I suggest you follow this link. Before jumping to the implementation with OAuth model, let's refresh our mind with a quick review of basic OAuth mechanism.

OAuth Authentication Basics

OAuth is the industry-standard authorization method and is used on various platforms. It's an open authorization model based primarily on existing standards that ensures secure credentials can be provisioned and verified by different software platforms. The simplest definition can be OAuth protocol enables users to provide third-party access to their web resources without sharing their passwords (You will find details about the authentication here). OAuth is a secure and quick way to publish and access private data, such as contact lists and updates, and this is why I choose OAuth model to retrieve users' contact information.
Figure 1: Basic OAuth model
You can download the sample code/documentation compatible for .NET from the links below

Setting up Yahoo! OAuth

In order to use the Yahoo! OAuth, we have to follow a series of steps:
  • Sign Up and Get a Consumer Key: Before you can start making Yahoo! API requests, you need to sign up and submit some details about your application.
  • Get a Request Token: The Request Token is a temporary token used to initiate User authorization for your application. The Request Token tells Yahoo! that you've obtained User approval.
  • Get User Authorization: After getting the Request Token from Yahoo!, your application presents to your Users a Yahoo! authorization page asking them to give permission to your application to access their data.
  • Exchange the Request Token and OAuth Verifier for an Access Token: After your Users authorize your application access to their information, your application needs to exchange the approved Request Token for an Access Token, which tells Yahoo! that your application has been given authorization to access User data.
  • Refresh the Access Token: You can use the Access Token for one hour until it expires. To get a new Access Token for continued use, use the same expired token and the get_token call to be provided a new Access Token.
Let's see how OAuth works with Yahoo! API:
oAuth
Figure 2: Yahoo! OAuth model

Setting Up an API Key

You can request for an API key by navigating this link. You have to fill up the web form before you request for a key. There are 2 steps. The first step is filling out app specific information and request for an API key and the second step is to specify what services can be accessible by the API key. You can choose to access all public resources or alternatively, you can specify which services you are particularly interested in.

Step 1: Setting up App Information & Get API Key

Figure 3: Setting up app information
Configuration Notes
  • Application URL: This is the URL where your application resides.You can point out the root of the application here. For my app, I mentioned http:www.imgalib.com/ as app URL.
  • Choose an appropriate application name (my application name is qcontactreader).
  • Specify app kind, my sample app is web based.
  • Provide a small description about your application.
  • Access scope: Choose "This app requires access to private user data." option as my sample app is going to access the user contact list.
  • Hit Get API key and you are ready to roll.

Step 2 : Specify Permissions with the API Key

Figure 4: Specify permissions
Configuration Notes
  • Choose Yahoo Contact API and allow read permission. This API allows the app to view and/or import a user's Contacts data from the Yahoo! Contacts application.
Please remember the notes mentioned above are used to configure an app based on my needs. Feel free to configure according to your app needs.

Using the Sample Code

The sample code is simplified with the steps mentioned in Fig: 2. As mentioned in step 2 function:
private string GetRequestToken()
{
        string authorizationUrl = string.Empty;
        OAuthBase oauth = new OAuthBase();

        Uri uri = new Uri("https://api.login.yahoo.com/oauth/v2/get_request_token");
        string nonce = oauth.GenerateNonce();
        string timeStamp = oauth.GenerateTimeStamp();
        string normalizedUrl;
        string normalizedRequestParameters;
        string sig = oauth.GenerateSignature
  (uri, ConsumerKey, ConsumerSecret, string.Empty, 
  string.Empty, "GET", timeStamp, nonce, 
  OAuthBase.SignatureTypes.PLAINTEXT, out normalizedUrl, 
  out normalizedRequestParameters); //OAuthBase.SignatureTypes.HMACSHA1
        StringBuilder sbRequestToken = new StringBuilder(uri.ToString());
        sbRequestToken.AppendFormat("?oauth_nonce={0}&", nonce);
        sbRequestToken.AppendFormat("oauth_timestamp={0}&", timeStamp);
        sbRequestToken.AppendFormat("oauth_consumer_key={0}&", ConsumerKey);
        sbRequestToken.AppendFormat("oauth_signature_method={0}&", 
     "PLAINTEXT"); //HMAC-SHA1
        sbRequestToken.AppendFormat("oauth_signature={0}&", sig);
        sbRequestToken.AppendFormat("oauth_version={0}&", "1.0");
        sbRequestToken.AppendFormat("oauth_callback={0}", 
 HttpUtility.UrlEncode("http://www.imgalib.com/demo/yahoo-oauth/default.aspx"));
        ..........
        ..........
        ...........
}
This function builds request to connect with Yahoo! through oAuth and receives Request token and with this token now requests to access user address book by requesting access token:
private void GetAccessToken(string oauth_token, string oauth_verifier)
 {
     OAuthBase oauth = new OAuthBase();

        Uri uri = new Uri("https://api.login.yahoo.com/oauth/v2/get_token");
        string nonce = oauth.GenerateNonce();
        string timeStamp = oauth.GenerateTimeStamp();
        string sig = ConsumerSecret + "%26" + OauthTokenSecret;

        StringBuilder sbAccessToken = new StringBuilder(uri.ToString());
        sbAccessToken.AppendFormat("?oauth_consumer_key={0}&", ConsumerKey);
        sbAccessToken.AppendFormat("oauth_signature_method={0}&", 
     "PLAINTEXT"); //HMAC-SHA1
        sbAccessToken.AppendFormat("oauth_signature={0}&", sig);
        sbAccessToken.AppendFormat("oauth_timestamp={0}&", timeStamp);
        sbAccessToken.AppendFormat("oauth_version={0}&", "1.0");
        sbAccessToken.AppendFormat("oauth_token={0}&", oauth_token);
        sbAccessToken.AppendFormat("oauth_nonce={0}&", nonce);
        sbAccessToken.AppendFormat("oauth_verifier={0}", oauth_verifier);
        ................
        ................
 }
This step will prompt the user with a permission window. If user allows app to read his/her contact list, then the list is retrieved by:
private void RetriveContacts()
 {
    Uri uri = new Uri("http://social.yahooapis.com/v1/user/" + 
  OauthYahooGuid + "/contacts?format=XML");
    .........
    .........
 }
If you want to run the sample code, you have to go through a couple of steps, and that starts with setting up an API key described above. Then host the app at the server as Yahoo! needs to communicate with your provided callback URL. Open default.aspx and change these property values with your respective registered key:
public string ConsumerKey
    {
        get
        {
            return "YOUR_CONSUMER_KEY";
        }
    }
public string ConsumerSecret
    {
        get
        {
            return "YOUR_CUSTOMER_SECRET_KEY";
        }
    }
Open the GetRequestToken() function, change the callback URL with your callback URL:
sbRequestToken.AppendFormat("oauth_callback={0}", 
 HttpUtility.UrlEncode("http://www.yoursite.com/yahoo-oauth/default.aspx"));
That's it, you are ready to go. You can also navigate to this link to find more details about Yahoo! oauth request format or regarding contact API. Also, you can download the library used for this sample code from here.