NAME

Flickr::API - Perl interface to the Flickr API

SYNOPSIS

Using OAuth to call a method not requiring authentication

  use Flickr::API;

  my $api = Flickr::API->new({
        'consumer_key'    => 'your_api_key',
        'consumer_secret' => 'your_app_secret',
    });

  my $response = $api->execute_method('flickr.test.echo', {
        'foo' => 'bar',
        'baz' => 'quux',
    });


  my $config_file = $HOME/saved-flickr.st;
  $api->export_storable_config($config_file);

Non-OAuth method calling method not requiring authentication

  use Flickr::API;

  # key deprecated in favor of api_key
  # secret deprecated in favor of api_secret
  #
  my $api = Flickr::API->new({
        'api_key'    => 'your_api_key',
        'api_secret' => 'your_app_secret',
    });

  my $response = $api->execute_method('flickr.test.echo', {
        'foo' => 'bar',
        'baz' => 'quux',
    });

Alternatively, Using OAuth for non-authenticated request

  use Flickr::API;
  use Flickr::API::Request;

  my $api = Flickr::API->new({'consumer_key' => 'your_api_key','consumer_secret' => 'your_app_secret'});

  my $request = Flickr::API::Request->new({
        'method' => 'flickr.test.echo',
        'args' => {},
    });

  my $response = $api->execute_request($request);

Authenticate an OAuth API Object starting with saved configuration

  use Flickr::API;
  use Term::ReadLine;

  my $config_file = "$ENV{HOME}/saved-flickr.st";
  my $term   = Term::ReadLine->new('Testing Flickr::API');
  $term->ornaments(0);

  my $api = Flickr::API->import_storable_config($config_file);

  my $rt_rc =  $api->oauth_request_token( { 'callback' => 'https://127.0.0.1/' } );

  my %request_token;
  if ( $rt_rc eq 'ok' ) {

      my $uri = $api->oauth_authorize_uri({ 'perms' => 'read' });

      my $prompt = "\n\n$uri\n\n" .
          "Copy the above url to a browser, and authenticate with Flickr\n" .
          "Press [ENTER] once you get the redirect: ";
      my $input = $term->readline($prompt);

      $prompt = "\n\nCopy the redirect URL from your browser and enter it\nHere: ";
      $input = $term->readline($prompt);

      chomp($input);

      my ($callback_returned,$token_received) = split(/\?/,$input);
      my (@parms) = split(/\&/,$token_received);
      foreach my $pair (@parms) {

          my ($key,$val) = split(/=/,$pair);
          $key =~ s/oauth_//;
          $request_token{$key}=$val;

      }
  }

  my $ac_rc = $api->oauth_access_token(\%request_token);
  if ( $ac_rc eq 'ok' ) {

      $api->export_storable_config($config_file);

      my $response = $api->execute_method('flickr.auth.oauth.checkToken');
      my $hash_ref = $response->as_hash();

      $response    = $api->execute_method('flickr.prefs.getPrivacy');
      my $rsp_node = $response->as_tree();
  }

The OAuth authorization uri will look something like:

  https://api.flickr.com/services/oauth/authorize?oauth_token=12345678901234567-890abcdefedcba98&perms=read

The callback is called with a token and verifier such as:

  https://127.0.0.1/?oauth_token=12345678901234567-890abcdefedcba98&oauth_verifier=cafe12345678feed

DESCRIPTION

An interface for using the Flickr API.

"Flickr::API" is a subclass of LWP::UserAgent, so all of the various proxy, request limits, caching, etc are available. "Flickr::API" can instantiate using either the Flickr Authentication (deprecated) or the OAuth Authentication. OAuth is handled using Net::OAuth.

SUBROUTINES/METHODS

"new({ opt => 'value', ... })": Returns as new Flickr::API object. The options are as follows:

either "api_key" for the Flickr auth or "consumer_key" for OAuth: Your API key (one or the other form is required)
either "api_secret" for the Flickr auth or "consumer_secret" for OAuth: Your API key's secret (the one matching the api_key/consumer_key is required)
"rest_uri" & "auth_uri": Override the URIs used for contacting the API.
"lwpobj": Base the "Flickr::API" on this object, instead of creating a new instance of LWP::UserAgent. This is useful for using the features of e.g. LWP::UserAgent::Cached.
"unicode": This flag controls whether Flickr::API expects you to pass UTF-8 bytes (unicode=0, the default) or actual unicode strings (unicode=1) in the request.
"nonce", "timestamp", "request_method", "signature_method", "request_url": These values are used by Net::OAuth to assemble and sign OAuth consumer request Flickr API calls. The defaults are usually fine.
"callback": The callback is used in oauth authentication. When Flickr authorizes you, it returns the access token and access token secret in a callback URL. This defaults to https://127.0.0.1/
"token" and "token_secret": These values are used by Net::OAuth to assemble and sign OAuth protected resource request Flickr API calls.

"execute_method($method, $args)"

Constructs a Flickr::API::Request object and executes it, returning a Flickr::API::Response object.

"execute_request($request)"

Executes a Flickr::API::Request object, returning a Flickr::API::Response object. Calls are signed if a secret was specified when creating the Flickr::API object.

"request_auth_url($perms,$frob)"

Returns a URI object representing the URL that an application must redirect a user to for approving an authentication token.

$perms must be read, write, or delete.

For web-based applications $frob is an optional parameter.

Returns undef if a secret was not specified when creating the "Flickr::API" object.

"export_config([$type,$params])"

Returns a hash of all or part of the persistent parts of the Flickr::API object with additional behaviors for Flickr::API objects using OAuth.

oauth message type: one of "Consumer", "Protected Resource", "Request Token", "Authorize User" or "Access Token": This is one of the the message type that Net::OAuth handles. Message type is optional.
oauth parameter set: "message" or "API" or undef.: Net::OAuth will return message params, api params or all params depending on what is requested. All params is the default.

If the Flickr::API object identifies as Flickr original authentication, return a hashref

  $VAR1 = {
            'frob' => '12332112332112300-feedabcde123456c-1234567',
            'api_key' => 'cafefeedbeef13579246801234567890',
            'api_secret' => 'beef321432154321',
            'token' => '97531086421234567-cafe123456789abc'
          };

or the subset thereof depending on what has been used by the API. If the older form of key/secret was used, the constructor will change these to the api_key/api_secret forms.

If the API object identifies as OAuth authentication, and "message type" is specified, then export_config will return a hash of the OAuth parameters for the specified Net::OAuth message type. Further, if parameter is specified, then export_config returns either either the set of message parameters or api parameters for the message type. If parameter is not specified then both parameter type are returned. For example:

  my %config = $api->export_config('protected resource');

  my %config = $api->export_config('protected resource','message');

When export_config is called without arguments, then it returns the OAuth portion of the Flickr::API object. If present the Net::OAuth Request Token and Access Token objects are also included.

  VAR1 = {
            'access_token' => bless( {
                                       'extra_params' => {
                                                           'fullname' => 'Louis',
                                                           'user_nsid' => '12345678@N00',
                                                           'username' => 'meanameicallmyself'
                                                         },
                                       'from_hash' => 1,
                                       'token' => '12345678901234567-cafe123098765432',
                                       'token_secret' => 'eebeef000fedbca1'
                                     }, 'Net::OAuth::AccessTokenResponse' ),
            'callback' => 'https://127.0.0.1',
            'consumer_key' => 'cafefeedbeef13579246801234567890',
            'consumer_secret' => 'fedcba9876543210',
            'nonce' => '917fa882fa7babd5a1b7702e7d19502a',
            'request_method' => 'GET',
            'request_url' => 'https://api.flickr.com/services/rest/',
            'signature_method' => 'HMAC-SHA1',
            'timestamp' => 1436129308,
            'token' => '12345678901234567-cafe123098765432',
            'token_secret' => 'eebeef000fedbca1',
            'version' => '1.0'
          };

  my %config = $api->export_config();

This method can be used to extract and save the API parameters for future use.

"export_storable_config(filename)": This method wraps export_config with a file open and storable store_fd to add some persistence to a Flickr::API object.
"import_storable_config(filename)": This method retrieves a storable config of a Flickr::API object and revivifies the object.
"get_oauth_request_type()": Returns the oauth request type in the Flickr::API object. Some Flickr methods will require a "protected resource" request type and others a simple "consumer" request type.
"oauth_request_token(\%args)": Assembles, signs, and makes the OAuth Request Token call, and if sucessful stores the Net::OAuth Request Token in the Flickr::API object.
The required parameters are:

"consumer_key": Your API Key
"consumer_secret": Your API Key's secret
"request_method": The URI Method: GET or POST
"request_url": Defaults to: <https://api.flickr.com/services/oauth/request_token>

"flickr_access_token": The required parameters are:

"key"

"oauth_access_token(\%args)": Assembles, signs, and makes the OAuth Access Token call, and if sucessful stores the Net::OAuth Access Token in the Flickr::API object.
The required parameters are:

"consumer_key": Your API Key
"consumer_secret": Your API Key's secret
"request_method": The URI Method: GET or POST
"request_url": Defaults to: <https://api.flickr.com/services/oauth/access_token>
"token_secret": The request token secret from the Net::OAuth Request Token object returned from the oauth_request_token call.

"oauth_authorize_uri(\%args)": Returns a URI object representing the URL that an application must redirect a user to for approving a request token.

"perms": Permission the application is requesting, one of read, write, or delete, defaults to read.

"is_oauth": Returns 1 if the Flickr::API object is OAuth flavored, 0 otherwise.

AUTHOR

Cal Henderson, <cal@iamcal.com>

Auth API patches provided by Aaron Straup Cope

Subclassing patch from AHP

OAuth patches and additions Louis B. Moore <lbmoore@cpan.org>

LICENSE AND COPYRIGHT

This program is released under the Artistic License 2.0 by The Perl Foundation.