Updates API Demo

Yahoo! Updates API Demo

On this page, we're going to walk you through an example illustrating how the Yahoo! Updates API works on a partner site.

In this example, Mike wants to have his readers be able to rate their favorite TV shows on his blog. As his readers are performing social actions on his site (rating the TV shows), those actions are getting broadcasted to others on the Yahoo! network via the Yahoo! Updates stream.

Before you get started

In order to completely understand the power of this demo, you'll want to open a new tab or window and log in to your Yahoo! Profile page. If you don't yet have a Yahoo! Profile, take a few seconds to create one. Look at the existing updates on your Yahoo! Profile page before you run the demo. This is where the updates will be published.

The example displayed below shows a mock partner site with fictitious content within an iframe. We are displaying the example in an iframe to show that the file could exist anywhere off the Yahoo! Network.

Demo on a Partner Site

Instructions

In the demo, click on a rating for a TV show. A rating will be saved for Mike's blog.
A "Share via Yahoo!" button will appear. Click on the button.
A new window will open, presenting you with the Yahoo! Login and Authorization pages. Fill out the appropriate information and then close the window.
Now, refresh your profile (that you opened in another tab or window) and check your updates. You should see that the rating you selected on Mike's TV blog were published on your Yahoo! Profile.

View the demo in a new window.

How It Works

Getting Started

Get an API Key
Get our PHP SDK
Download and install the demo application, and set your application ID and consumer keys.

Setup and Configuration

After creating a new application, you are issued an application ID, a consumer key, and a secret key that are used to identify your application to Yahoo! and needed by the SDK to complete authorization. In this example, these values are stored in a config.inc.php file for easy access.

Rating Submission

When a star rating form is submitted (when a star is selected), an Ajax request is POSTed to the applications rate.php script containing the rating form using the YUI Connection Manager.

OAuth

Once the application has made the request to rate.php, that script will check for an existing user session by checking for the presence of an access token in the browser cookie.

An access token is needed by the application to post updates to Yahoo!. If one does not exist, we can get one by going through the first two steps of the OAuth authorization. First, we will request a Request Token from Yahoo!, then use it to construct the authorization URL. This will be returned as part of an error response of rate.php, signaling to the application that the user will need to login.

User Authorization

Once the application has received the response from rate.php, it will check for an error flag stating that the user needs to login before an update can be pushed out.

A prompt is displayed to the user with a link to the authorization URL that we just generated.

Once the user returns to the application after authenticating—through the callback URL we supplied—there is only one step left before sending an update. This last step through OAuth is to obtain an access token by passing the application credentials and the now authorized request token.

Luckily, our RatingUtil class and the SDK will handle this nicely for us. By instantiating a new RatingUtil object, the code will check for a session through the SDK, and if one exists, a new session is created and stored for future use.

Creating an Update

Now that we have an ready session, we are able to communicate with the social APIs. Using the query string passed through the callback URL, we still have the users original rating form entry. Using that data, we can create a session and push a new update out.

At this point, a new update has been published. Because we now have the access token stored in the user cookie, we can retrieve it (and refresh the token, if needed) at any time to create a new session.

This means that if the user submits another rating form, we can push an update immediately without sending the user back through OAuth.

Back in rate.php, if the user has a session, we'll publish an update and return a success response to our application, rather than our previous action of initializing the OAuth flow.

That's it! You've now made it through OAuth and are now pushing updates to Yahoo!.

Appendix: RatingUtil.inc.php

RatingUtil.inc.php is fully shown here so you can see the methods being called by rate.php and oauth_callback.php. This class contains the OAuth consumer token, the session, the session store, and the application ID for easy access. It also contains methods for creating an authorization URL and inserting an update.

// RatingUtil.inc.php

include "config.inc.php";
include "lib/Yahoo.inc";

class RatingUtil
{
   public $hasSession;
   public $sessionStore;
   public $session;

private $_consumer;
   private $_appid;

/**
   *  Class constructor
   *  Sets session credentials and checks session
   */
   public function RatingUtil()
   {
      $this->sessionStore = new CookieSessionStore();

$this->_appid = APPID;

$consumer = new stdclass();
      $consumer->key = CONSUMER_KEY;
      $consumer->secret = CONSUMER_SECRET;

$this->_consumer = $consumer;

$this->createSession();
   }

/**
   * Checks for and creates a session if valid.
   * The SDK will automatically request an access token
   * if an authorized request token is found.
   */
   private function createSession()
   {
      $this->hasSession = YahooSession::hasSession($this->_consumer->key,
                           $this->_consumer->secret, $this->_appid,
                           $this->sessionStore);

if($this->hasSession) {
         $this->session = YahooSession::requireSession($this->_consumer->key,
                           $this->_consumer->secret, $this->_appid,
                           NULL, $this->sessionStore);
      }
   }

/**
   * Handles the creation of an unique update ID and pushing
   * the update data through the SDK.
   */
   public function insertUpdate($title, $link, $description="")
   {
      $user = $this->session->getSessionedUser();
      $guid = $user->guid;

// generate a unique id by hashing each update field
      $suid = md5($title.$link.$description.$rating.$guid.time());

// pass the update fields to the sdk to send the request
      $update = $user->insertUpdate($suid, $title, $link, $description);

$rsp = array();
      $rsp['update'] = $update;
      $rsp['suid'] = $suid;

return $rsp;
   }

/**
   * Creates an OAuth authorization URL given a callback URL.
   * Will automatically fetch a request token.
   */
   public function createAuthorizationUrl($callbackUrl)
   {
      $token = $this->createRequestToken($callbackUrl);
      return YahooAuthorization::createAuthorizationUrl($token);
   }

/**
   * Fetches and stores an OAuth request token to be authorized by the user.
   */
   private function createRequestToken($callbackUrl)
   {
      $token = YahooAuthorization::getRequestToken($this->_consumer->key,
                  $this->_consumer->secret, $callbackUrl);

$stored = $this->sessionStore->storeRequestToken($token);

return $token;
   }
}

Ready to get started?

By accessing Yahoo! Updates data, you hereby agree to the Terms of Use

Download the Demo Read the Documentation

Yahoo! Developer Network