table of contents
| Flickr::API(3pm) | User Contributed Perl Documentation | Flickr::API(3pm) | 
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');
or
  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
      successful 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
      successful 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¶
Copyright (C) 2004-2013, Cal Henderson, <cal@iamcal.com>
OAuth patches and additions Copyright (C) 2014-2016 Louis B. Moore <lbmoore@cpan.org>
This program is released under the Artistic License 2.0 by The Perl Foundation.
SEE ALSO¶
Flickr::API::Request, Flickr::API::Response, Net::OAuth, XML::Parser::Lite, Flickr <http://www.flickr.com/>, <http://www.flickr.com/services/api/> <https://www.flickr.com/services/api/auth.oauth.html> <https://github.com/iamcal/perl-Flickr-API>
| 2018-08-14 | perl v5.26.2 |