Step by Step Guide to Delicious OAuth API
4.81/5 (11 votes)
Learn how to use Delicious OAuth API in your .NET projects with an example
Introduction
After merging with yahoo, Delicious's account registration is done using yahoo account. Moreover OAuth has been introduced for accessing Delicious's API. A guideline has been provided in Delicious's help page at http://delicious.com/help/oauthapi describing the steps to use their API, but that is not so very illustrative. Also, no readily usable sample project or dll is available on the internet. So I have decided to write a sample application for accessing Delicious's OAuth API.
What is OAuth?
OAuth (Open Authorization) is an open protocol that allows users to share their private resources (e.g. photos, videos, contact lists) stored on one site with another site without having to hand out their username and password.
OAuth allows users to hand out tokens instead of usernames and passwords to their data hosted by a given service provider like delicious, twitter, linkedin etc.
Steps to call Delicious API
Following are the steps to make a successful API call to delicious using OAuth.
- Get an API key
- Get a Request Token
- Get user permission to access their data
- Get an Access Token
- Create the request for Delicious
- Refresh Access Token for future API calls without authorization
1. Get an API key
To access any API using OAuth, a consumer/API Key and a consumer/API Secret Key are required. These can be obtained from Yahoo! Developer Network (YDN) API key form. Fill up this form appropriately and set the access scope eg to which of the yahoo owned site(s) you need API access.
Following two figures illustrates the steps to obtain OAuth access keys:
Figure 1: API key form page
Figure 2: API key confirmation page
From this step you will get following key information:
- an Application Id
aFWQnp1s - an API Key (OAuth consumer key)
ef1uGeq4fP9vbnDXQAtlN0IcKvY8RTef0MztKJfBRYacPiuYmQXFdi10DOU3WSDVfn7MQw5basdrn92urX47wlD3F6G4oOA6JHE6 - a Shared/Consumer Secret
1e782b9c13315e30d2fbac12348942cc9db674f2
2. Get a Request Token
After getting the API keys, make a request to the YDN API at the following URL:
https://api.login.yahoo.com/oauth/v2/get_request_token
Include the following parameters:
| Request Parameter | Description |
|---|---|
| oauth_nonce | A random string. |
| oauth_timestamp | Current timestamp of the request. This value must be +/-600 seconds of the current time. |
| oauth_consumer_key | Your consumer key. |
| oauth_signature_method | The signature method that you use to sign the request. This can be plaintext or hmac-sha1. |
| oauth_signature | Your shared secret. |
| oauth_version | OAuth version (1.0) |
| xoauth_lang_pref | (optional) The language preference of the User; the default value is en-us. |
| oauth_callback | Your callback url as set up in the YDN process. |
Your request should look something like the following:
https://api.login.yahoo.com/oauth/v2/get_request_token?
Please note that you must include all the parameters specified above (except ‘xoauth_lang_pref’ which is optional) even though it might seem irrelevant in your case eg in desktop application ‘oauth_callback’ may not be required but still you need to put it in the request url. ‘http://localhost/’ might be a sample value.
This should result in a response similar to:
oauth_token%3Drpfbncv%26oauth_token_secret%3D5f2e792b36c40edaf7bdd8fb10b6edd1fde87a52
which can be parsed to get:
- oauth_token
- oauth_token_secret
- oauth_expires_in
- xoauth_request_auth_url
- oauth_callback_confirmed
3. Get user permission to access their data
To access any data form any of the user’s account, user’s explicit permission is required. To get this permission, we need to redirect the user to the url given in xoauth_request_auth_url with some additional parameters.
Your query parameters should be formed something like this:
<xoauth_request_auth_url>&oauth_nonce=
Actual request URL would look like following:
https://api.login.yahoo.com/oauth/v2/request_auth?
Visiting this URL, user can accept or deny permission to his/her private data. If user permits access to his/her account, an email will be sent to his/her mail account with a link to revoke permission (if required).
4. Get an Access Token
Once the user has given permission for your app to access their data, all callback will be made back to your application in the following format:
<your callback url>?oauth_token=<request token>&oauth_verifier=<verifier>
eg
http://mysite.com/callbackurl.aspx?oauth_token=rpfbncv&oauth_verifier=burykq
Using the oauth_verifier parameter from above, and the oauth_token and oauth_token_secret (obtained in Step 2), request an access token, like this:
https://api.login.yahoo.com/oauth/v2/get_token?oauth_consumer_key=<your consumer key>&oauth_signature_method=plaintext&oauth_version=1.0&oauth_verifier=<oauth_verifier>&oauth_token=<request_token>&oauth_nonce=<random string>&oauth_timestamp=<current timestamp>&oauth_signature=<your consumer secret>%26<request token secret>
eg
https://api.login.yahoo.com/oauth/v2/get_token?
The response to this request should be an access token string, something like:
oauth_token=A%3DvVzfAVXKsgHcbN6CCBdkiHFN6dOVXHRp6j_
From which you can extract:
- oauth_token
- oauth_token_secret
- oauth_expires_in
- oauth_session_handle
- oauth_authorization_expires_in
- xoauth_yahoo_guid
5. Create the request for Delicious
Calling the Delicious API is performed in three steps:
a. Building the “Base String”
At his point, we have all the necessary information to call the delicious API. But building the request with required parameters is really tricky and 90% of the developers got stuck here. So carefully follow each word of the instructions written below.
Suppose we need to call API http://api.del.icio.us/v2/posts/suggest to get suggestions for http://www.yahoo.com/ eg the full request url is http://api.del.icio.us/v2/posts/suggest?url=http://www.yahoo.com/.
At frist, build a base string as instructed below:
- Take all the request parameters that you want to send to the API. In our case, this will be:
- the url
- oauth_consumer_key
- oauth_nonce
- oauth_signature_method
- oauth_timestamp
- oauth_token
- oauth_version
Then sort these parameters alphabetically, url encode each of the values and build a string of the format:
<param1>=<value1>&<param2=<value2>&...&<paramN>=<valueN>
eg
oauth_consumer_key=ef1uGeq4fP9vbnDXQAtlN0IcKvY8RTef0MztKJfBRYacPiuYmQXFdi10DOU3WSDVfn 7MQw5basdrn92urX47wlD3F6G4oOA6JHE6 &oauth_nonce=613149020&oauth_signature_method=HMAC-SHA1 &oauth_timestamp=1257971461 &oauth_token=A%3DvVzfAVXKsgHcbN6CCBdkiHFN6dOVXHRp6j_.rp. k8rZGUEC90xB..TVkGkt84PFgY3ju3TR22mG4SmKRQxGZUxg. VHhRs89mhh97wBSwjShz88wljdPupz0..bsTIymGIAlJVosVocN nTwPYLp.UFcCEdFKklYcs.KUDRhdtffP8cLp8dGFzUfWxdwQk45eDA B0e.VJmG5jUc6p_mGvsnappYfoIdzoP13Dz6v3W4Oi8ygW8W10Z. x9aFxL1m4ZkaIWxUm85DxG.yvgNTzi2h5qqhJBbJKP0ZX2tm7DTH7hksW FrMevkJaKwkHgzN3N8bUA3tnW5xii4LAzRb87W8GaSQ27gH4WBX9pr Nstqw4KtTdvMS9QJw9ckid5w0U1DB25cAniZXimXXybOwaj5u2QHG6z KloGZxFlLhc.wELxOhuymBEuVAwP2s.BWrzTh9QrSopOCeY9S SkEN0fjHZ5jFmaxStgWJQQysDU3JWuor2SvWmOB5I5q2vYCZrL5IYncMofHm6JUWkm5R6NAQt_. kO8wF8ZamiDzCE2iBi91HJlrkCb3.lV804Xs7M4sbD_MHa3UV7x7iw6XEhLjc tD8al0BGVjooKYaxObrBygTTtngdtkXZSxJI.hLfcAo3TymujkAfycVGSscHA l_IeEvNUIJnOX4jB1dDdzfoSk_83rFiCLsRasRjxLHv.o.ltfoUV pL4fL_1cP2rwh2Drxvpwup1dReSr2GtSsbGig-- &oauth_version=1.0 &url=http%3A%2F%2Fwww.yahoo.com%2F - Combine the request parameters with the HTTP Method being used (usually GET or POST), and the API url:<method>&<api url>&<request parameters>
Note: the <api url> and the <request parameters> must be url encoded. Though we url encoded all the parameter values separately in the last step, we need to url encode them combining the key/value pairs.
eg
GET&http%3A%2F%2Fapi.del.icio.us%2Fv2%2Fposts%2Fsuggest
&oauth_consumer_key%3Def1uGeq4fP9vbnDXQAtlN0IcKvY8RTef0MztKJfBRYacPi uYmQXFdi10DOU3WSDVfn7MQw5basdrn92urX47wlD3F6G4oOA 6JHE6%26oauth_nonce%3D613149020 %26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1257971461 %26oauth_token%3DA%253DvVzfAVXKsgHcbN6CCBdkiHFN6dOVXHRp6j_. rp.k8rZGUEC90xB..TVkGkt84PFgY3ju3TR22mG4SmKRQxGZUxg.VHhRs89mhh97wBSw jShz88wljdPupz0..bsTIymGIAlJVosVocNnTwPYLp.UFcCEdFKklYcs.KUDRhdtffP8cLp8dGFzUfW xdwQk45eDAB0e.VJmG5jUc6p_mGvsnappYfoIdzoP13Dz6v3W4Oi8yg W8W10Z.x9aFxL1m4ZkaIWxUm85DxG.yvgNTzi2h5qqhJBb JKP0ZX2tm7DTH7hksWFrMevkJaKwkHgzN3N8bUA3tnW 5xii4LAzRb87W8GaSQ27gH4WBX9prNstqw4KtTdvM S9QJw9ckid5w0U1DB25cAniZXimXXybOwaj5u2Q HG6zKloGZxFlLhc.wELxOhuymBEuVAwP2s.BWrzTh 9QrSopOCeY9SSkEN0fjHZ5jFmaxStgWJQQysDU3JWuor2SvWmOB5I 5q2vYCZrL5IYncMofHm6JUWkm5R6NAQt_.kO8wF8 ZamiDzCE2iBi91HJlrkCb3.lV804Xs7M4sbD_MHa3UV7x7iw6XEhL jctD8al0BGVjooKYaxObrBygTTtngdtkXZSxJI.hLfcAo3TymujkAfycVGSsc HAl_IeEvNUIJnOX4jB1dDdzfoSk_83rFiCLsRasRjxLHv.o. ltfoUVpL4fL_1cP2rwh2Drxvpwup1dReSr2GtSsbGig-- %26oauth_version%3D1.0%26url%3Dhttp%253A%252F%252Fwww.yahoo.com%252F
Note: Here always the confusion arises which parameters to include in the base string and which not. Actually you need to include all the parameters both oauth’s ones (like
oauth_consumer_key,oauth_tokenetc.) and requested API’s ones (urlfor this example). If API url contains no parameter (eg http://api.del.icio.us/v2/posts/) then only oauth’s parameters will do and if the API url (eg http://api.del.icio.us/v2/posts/get?tag=programming&dt=2010-04-10T15:10:56Z) contains more parameters (egtaganddtin this case) these also need to be included in the base string. FYI – date parameter’s (egdt) value must be universal time and should be formatted asyyyy-MM-ddTHH:mm:ssZ.
b. Generate the signature
This step is very critical and prone to make more mistakes. Anyway, in this step you need to create a signature using HMAC-SHA1 signature algorithm.
In PHP you can build this signature very easily as code shown below:
<?php $signature = base64_encode(hash_hmac(‘sha1', <base string>, <shared secret>.’&’.<access token secret>, true)); ?>
eg
<?php $signature = base64_encode(hash_hmac('sha1', GET&http%3A%2F%2Fapi.del.icio.us%2Fv2%2Fposts%2Fsuggest&oauth_consumer_key%3Def1uGeq4fP9vbnDXQAtlN0IcKvY8RTef0MztKJfBRYacPiuYmQXFdi10DOU3WSDVfn7MQw5basdrn92urX47wlD3F6G4oOA6JHE6%26oauth_nonce%3D613149020%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1257971461%26oauth_token%3DA%253DvVzfAVXKsgHcbN6CCBdkiHFN6dOVXHRp6j_.rp.k8rZGUEC90xB..TVkGkt84PFgY3ju3TR22mG4SmKRQxGZUxg.VHhRs89mhh97wBSwjShz88wljdPupz0..bsTIymGIAlJVosVocNnTwPYLp.UFcCEdFKklYcs.KUDRhdtffP8cLp8dGFzUfWxdwQk45eDAB0e.VJmG5jUc6p_mGvsnappYfoIdzoP13Dz6v3W4Oi8ygW8W10Z.x9aFxL1m4ZkaIWxUm85DxG.yvgNTzi2h5qqhJBbJKP0ZX2tm7DTH7hksWFrMevkJaKwkHgzN3N8bUA3tnW5xii4LAzRb87W8GaSQ27gH4WBX9prNstqw4KtTdvMS9QJw9ckid5w0U1DB25cAniZXimXXybOwaj5u2QHG6zKloGZxFlLhc.wELxOhuymBEuVAwP2s.BWrzTh9QrSopOCeY9SSkEN0fjHZ5jFmaxStgWJQQysDU3JWuor2SvWmOB5I5q2vYCZrL5IYncMofHm6JUWkm5R6NAQt_.kO8wF8ZamiDzCE2iBi91HJlrkCb3.lV804Xs7M4sbD_MHa3UV7x7iw6XEhLjctD8al0BGVjooKYaxObrBygTTtngdtkXZSxJI.hLfcAo3TymujkAfycVGSscHAl_IeEvNUIJnOX4jB1dDdzfoSk_83rFiCLsRasRjxLHv.o.ltfoUVpL4fL_1cP2rwh2Drxvpwup1dReSr2GtSsbGig--%26oauth_version%3D1.0%26url%3Dhttp%253A%252F%252Fwww.yahoo.com%252F, 1e782b9c13315e30d2fbac12348942cc9db674f2.'&'.6a72597fdc62131f7167be3f9b4f31e955244bee, true)); ?>
This will result in the following string:
QAnF8ETJ0znTvcxBEb+MJoFicmQ=
In C#, you can also achieve this as code shown below:
HMACSHA1 hmacsha1 = new HMACSHA1();
hmacsha1.Key = Encoding.ASCII.GetBytes(string.Format("{0}&{1}", UrlEncode(), UrlEncode()));
string signature = Convert.ToBase64String(hashAlgorithm.ComputeHash(System.Text.Encoding.ASCII.GetBytes(data)));
Using c#, here you cannot directly use HttpUtility.UrlEncode() function as it encodes special characters like “/,\,:” etc. to lower case format like “%2f,%5c,%3a” whereas OAuth expects url encoding in upper case format like “%2F,%5C,%3A”. This issue needs to be considered while URL encoding.
c. Make the delicious API call
Finally, we are at the point of making a request to Delicious.
First, we need to create an Authorization Header to send in the request. To do this, take the parameters we used to generate the Base String, remove any parameters that were part of the actual API request (in our case “url”), and then ADD the signature we just generated in Stage 5b as an oauth_signature parameter. All parameters are then joined together in a comma separated string:
eg
Authorization: OAuth realm="yahooapis.com",oauth_consumer_key="ef1uGeq4fP9vbnDXQAtlN0IcKvY8
In c# we can add the header in the web request object as the code follows:
webRequest.Headers.Add("Authorization", "OAuth realm=\"yahooapis.com\",oauth_consumer_key=\"ef1uGeq4fP9vbnDXQAtlN0IcKvY8RTef0MztKJfBRYacPiuYmQXFdi10DOU3WSDVfn7MQw5basdrn92urX47wlD3F6G4oOA6JHE6\",oauth_nonce=\"613149020\",oauth_signature_method=\"HMAC-SHA1\",oauth_timestamp=\"1257971461\",oauth_token=\"A%3DvVzfAVXKsgHcbN6CCBdkiHFN6dOVXHRp6j_.rp.k8rZGUEC90xB..TVkGkt84PFgY3ju3TR22mG4SmKRQxGZUxg.VHhRs89mhh97wBSwjShz88wljdPupz0..bsTIymGIAlJVosVocNnTwPYLp.UFcCEdFKklYcs.KUDRhdtffP8cLp8dGFzUfWxdwQk45eDAB0e.VJmG5jUc6p_mGvsnappYfoIdzoP13Dz6v3W4Oi8ygW8W10Z.x9aFxL1m4ZkaIWxUm85DxG.yvgNTzi2h5qqhJBbJKP0ZX2tm7DTH7hksWFrMevkJaKwkHgzN3N8bUA3tnW5xii4LAzRb87W8GaSQ27gH4WBX9prNstqw4KtTdvMS9QJw9ckid5w0U1DB25cAniZXimXXybOwaj5u2QHG6zKloGZxFlLhc.wELxOhuymBEuVAwP2s.BWrzTh9QrSopOCeY9SSkEN0fjHZ5jFmaxStgWJQQysDU3JWuor2SvWmOB5I5q2vYCZrL5IYncMofHm6JUWkm5R6NAQt_.kO8wF8ZamiDzCE2iBi91HJlrkCb3.lV804Xs7M4sbD_MHa3UV7x7iw6XEhLjctD8al0BGVjooKYaxObrBygTTtngdtkXZSxJI.hLfcAo3TymujkAfycVGSscHAl_IeEvNUIJnOX4jB1dDdzfoSk_83rFiCLsRasRjxLHv.o.ltfoUVpL4fL_1cP2rwh2Drxvpwup1dReSr2GtSsbGig--\",oauth_version=\"1.0\",oauth_signature=\"QAnF8ETJ0znTvcxBEb%2BMJoFicmQ%3D\"");
We then add this header to our request that we are making for http://api.del.icio.us/v2/posts/suggest?url=http://www.yahoo.com/ and should get the expected response.
6. Refresh Access Token for future API calls without authorization
The access token obtained in step 4 remains valid for only 1 hour. So what happens after that period? Do you want to get authorization (by putting yahoo user id and password) again and again? What if you are writing a console application that will send updates of a delicious account to the subscribers at a regular interval? Well, don’t panic. A very feasible way is there.
You need to refresh the access token (using the expired token) to make subsiquent API calls.
The request url will look something like:
https://api.login.yahoo.com/oauth/v2/get_token?
All the request parameters are described below:
| Request Parameter | Description |
|---|---|
oauth_nonce |
A random string |
oauth_consumer_key |
Consumer Key provided to you when you sign up on the registration page. |
oauth_signature_method |
The signature method that you use to sign the request. This can be PLAINTEXT or HMAC-SHA1. |
oauth_signature |
The concatenated Shared Secret (Consumer Secret) and Token Secret separated by an “&” character. |
oauth_timestamp |
Current timestamp of the request. This value must be +-600 seconds of the current time. |
oauth_version |
OAuth version (1.0). |
oauth_token |
The expired Access Token. |
oauth_session_handle |
The persistent credential used by Yahoo! to identify the Consumer after a User has authorized access to private data. Include this credential in your request to refresh the Access Token once it expires. |
Conclusion
Delicious API will return all the results in xml format. You need to format it as per your requirement. Hope this will help.
(In this article I mainly followed and used some texts and code samples from http://delicious.com/help/oauthapi, Delicious.Net and LinkedinOauth).