/ 
Net-OAuth-Yahoo-0.05
River stage zero No dependents
/ Net::OAuth::Yahoo

NAME

Net::OAuth::Yahoo - Provides simple interface to access Yahoo! APIs

VERSION

Version 0.04

SYNOPSIS

use Net::OAuth::Yahoo;

# Construct hashref of OAuth information
my $args = {
    consumer_key => "dj0yJmk9TUhIbnlZa0tYVDAzJmQ9WVdrOWMyMUxNVXBoTjJNbWNHbzlNVGd3TnpjMU5qazJNZy0tJnM9Y29uc3VtZXJzZWNyZXQmeD1lNg--",
    consumer_secret => "93dfc3e0bbeec0c63b86b6f9f3c55772e4f1fe26",
    signature_method => "HMAC-SHA1",
    nonce => "random_string",
    callback => "oob",
};

my $oauth = Net::OAuth::Yahoo->new( $args );

# First, obtain the request token
my $request_token = $oauth->get_request_token();

# Second, fetch the OAuth URL to be presented to the user
my $url = $oauth->request_auth( $request_token );

# Third, obtain the OAuth Verifier.  The real way is to present the $url to the end user, have them click on the "Agree" button,
# then obtain the OAuth Verifier.  I wrote a simulator subroutine that does this, provided Yahoo ID and password.
# If you go with the real way, you can skip this step.
my $yid = {
    login => login,
    passwd => passwd,
};

my $oauth_verifier = $oauth->sim_present_auth( $url, $yid );

# Using the OAuth Verifier, let's get the token.
my $token = $oauth->get_token( $oauth_verifier );

# Now it's all done, time to access some API!
my $api_url = "http://fantasysports.yahooapis.com/fantasy/v2/team/265.l.5098.t.2/players?format=json";
my $json = $oauth->access_api( $token, $api_url );

OTHER METHODS:
The token expires after 1 hour, so you can reuse it until then.  3 methods are provided to facilitate the reuse.

# Save the token in a YAML file.
$oauth->save_token( "filename" );

# Load the token from a YAML file.
my $token = $oauth->load_token( "filename" );

# Test the token against an URL.  Returns 1 if good, 0 otherwise.
my $ret = $oauth->test_token( $token, $url );

TESTS:
Due to the nature of this module, information such as consumer_key, consumer_secret is required.  I have provided test_deeply.pl
in case the user wants to test the module deeply.  This test script prompts for various Net::OAuth information
as well as Yahoo login / password.

DEBUGGING:
This module returns "undef" if something goes wrong.  Also, an error message is set in $Net::Oauth::Yahoo::ERRMSG.
The user can inspect like so:
my $request_token = $oauth->get_request_token();
print $Net::OAuth::Yahoo::ERRMSG if ( !defined $request_token );

SUBROUTINES/METHODS

new

This is the constructor.  Takes a hashref of the following keys, and returns the Net::OAuth::Yahoo object.
my $args = {
    consumer_key => "dj0yJmk9TUhIbnlZa0tYVDAzJmQ9WVdrOWMyMUxNVXBoTjJNbWNHbzlNVGd3TnpjMU5qazJNZy0tJnM9Y29uc3VtZXJzZWNyZXQmeD1lNg--",
    consumer_secret => "93dfc3e0bbeec0c63b86b6f9f3c55772e4f1fe26",
    signature_method => "HMAC-SHA1",
    nonce => "random_string",
    callback => "oob",
};
my $oauth = Net::OAuth::Yahoo->new( $args );

get_request_token

This method talks to the Yahoo! login server then returns the request_token.  No argument is needed as the object contains
all the information it needs.
my $request_token = $oauth->get_request_token();

get_token

Takes the OAuth Verifier (the code that user presents to your webapp) and returns the access token.
my $token = $oauth->get_token( $oauth_verifier );

access_api

Takes a token and an URL then makes an API call againt the URL.  Data from Yahoo API is returned verbatim.
This means if you request JSON in the URL, then you'll get JSON back; otherwise XML.  
my $json = $oauth->access_api( $token, $url );

_make_oauth_request

A private method that abstracts Net::OAuth calls.  It is used internally by the object.

_validate_params

A private method that verifies parameters in the constructor.

request_auth

Takes a request token then returns the URL where the end user needs to access and grant your
webapp to access protected resources.
my $url = $oauth->request_auth( $request_token );

sim_present_auth

Takes an URL and hashref of Yahoo login / password information, then simulates the end user's action
of granting your webapp to access protected resources.  The method returns the OAuth verifier.
my $yid = {
    login => "some_login",
    passwd => "some_password",
}

my $oauth_verifier = $oauth->sim_present_auth( $url, $yid );

save_token

Takes a filename and dumps the token in YAML format.
$oauth->save_token( $file );

load_token

Takes a filename and loads token from the file.  Returns the token object.
my $token = $oauth->load_token( $file );

test_token

Takes a token object and URL to try fetching some data.  Returns 1 if success, 0 otherwise.
This method is useful to see if your loaded token has not expired.
my $ret_code = $oauth->test_token( $token );

get

Simple getter.  Returns object attributes if defined, undef otherwise.
my $token = $oauth->get( "token" );

AUTHOR

Satoshi Yagi, <satoshi.yagi at yahoo.com>

BUGS

Please report any bugs or feature requests to bug-net-oauth-yahoo at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-OAuth-Yahoo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::OAuth::Yahoo

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 Satoshi Yagi.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.