Flickr::API(3pm)

📦
version 1.29 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

🦋 Flickr::API — the Flickr::API(3pm) page, bestie edition 💖

User Contributed Perl Documentation · Flickr::API(3pm)

okay so. you wanna talk to Flickr from Perl. this is the module for that. pull up a chair, grab a boba, we're doing this together 🧋✨

✨ NAME ✨

Flickr::API — the Perl interface to the Flickr API. that's it, that's the whole name, and honestly? iconic. 💅

🌸 SYNOPSIS 🌸

🔐 Using OAuth to call a method not requiring authentication

no auth needed for this one, we're just vibing with OAuth:

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);

see how we just execute_method and then save the config with export_storable_config? chef's kiss. 🫶

🔓 Non-OAuth method calling method not requiring authentication

the old-school route. heads up tho:

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',
  });
lowkey important: key is deprecated in favor of api_key, and secret is deprecated in favor of api_secret. the comments literally say so, and we respect the comments. 🙈

🎀 Alternatively, Using OAuth for non-authenticated request

okay so this version is a little more ✨formal✨ — you build an actual Flickr::API::Request object first:

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);

note the execute_request($request) instead of execute_method(...). different function, same energy. 🔥

👑 Authenticate an OAuth API Object starting with saved configuration

this is the whole glow-up arc: load your saved config, get a request token, send your bestie (the user) to a browser, get the token back, trade it for an access token, save, party.

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 way this works is: oauth_request_token gives you $rt_rc, and if it comes back eq 'ok' you get the authorize URI with oauth_authorize_uri ('perms' => 'read' here), paste it in a browser, and then feed the redirect URL back into the prompt so we can split out the token. then oauth_access_token takes \%request_token, and if that returns eq 'ok' we export_storable_config($config_file) and go call flickr.auth.oauth.checkToken (grab it as as_hash()) and flickr.prefs.getPrivacy (grab it as as_tree()). two different response shapes, both valid. 💜

🔗 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 💫

so basically: an interface for using the Flickr API. that's the mission statement, we're keeping it simple. 🎀

and here's the fun part — Flickr::API is a subclass of LWP::UserAgent, which means all of the various proxy, request limits, caching, etc are available. you inherit the whole toolbox, no cap. 🧰

Flickr::API can instantiate using either the Flickr Authentication (which is deprecated, bestie — she's retired 💀) or the OAuth Authentication. and OAuth is handled using Net::OAuth. periodt. 💅

💖 SUBROUTINES/METHODS 💖

🌟 new({ opt => 'value', ... }) 🌟

okay so this is the constructor, right? you feed it a hash of options and it blesses you with a brand new Flickr::API object. the options go a little something like this:

  • either api_key for the Flickr auth or consumer_key for OAuth — that's your API key, bestie. one form or the other is required, no skipping 💅
  • either api_secret for the Flickr auth or consumer_secret for OAuth — your API key's secret. the one that matches whichever of api_key/consumer_key you picked is required.
  • rest_uri & auth_uri — override the URIs used for contacting the API. you know, if you're feeling custom ✨
  • lwpobj — base the Flickr::API on this object instead of making a whole new instance of LWP::UserAgent. super handy when you wanna use the features of, like, LWP::UserAgent::Cached. iconic behaviour tbh.
  • unicode — this flag decides whether Flickr::API expects you to hand it UTF-8 bytes (unicode=0, which is the default) or actual unicode strings (unicode=1) in the request. pick your fighter 🌈
  • nonce, timestamp, request_method, signature_method, request_url — Net::OAuth uses these to assemble and sign the OAuth consumer request Flickr API calls. the defaults are usually fine, don't stress 🫶
  • callback — the callback is used in oauth authentication. when Flickr authorizes you, it hands back the access token and access token secret in a callback URL. this defaults to https://127.0.0.1/
  • token and token_secret — Net::OAuth uses these to assemble and sign the OAuth protected resource request Flickr API calls.

🦋 execute_method($method, $args) 🦋

it builds a Flickr::API::Request object, runs it, and gives you back a Flickr::API::Response object. that's the whole vibe. ✨

🦋 execute_request($request) 🦋

runs a Flickr::API::Request object and returns a Flickr::API::Response object. and listen — calls get signed if you specified a secret when you created the Flickr::API object. no secret, no signature, iykyk.

🦋 request_auth_url($perms,$frob) 🦋

returns a URI object for the URL your app has to redirect a user to so they can approve an authentication token.

$perms must be read, write, or delete.

for web-based applications, $frob is an optional parameter.

it returns undef if a secret wasn't specified when you made the Flickr::API object. 😭

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

returns a hash of all — or part — of the persistent bits of the Flickr::API object, with some extra behaviours baked in 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 message types 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 you asked for. all params is the default.

if the Flickr::API object identifies as Flickr original authentication, you get back a hashref:

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

or the subset thereof, depending on what the API has actually used. and if the older form of key/secret was used, the constructor changes those into the api_key/api_secret forms. glow-up 💅

if the API object identifies as OAuth authentication and message type is specified, then export_config returns a hash of the OAuth parameters for the specified Net::OAuth message type. and further — if parameter is specified, then export_config returns either the set of message parameters or api parameters for the message type. if parameter is not specified, then both parameter types come back. for example:

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

or

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

when export_config is called with no arguments, it returns the OAuth portion of the Flickr::API object. and if they're present, the Net::OAuth Request Token and Access Token objects are included too. 🎀

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();

you can use this method to extract and save the API parameters for future use. future you says thank you. 🫶

🦋 export_storable_config(filename) 🦋

this one wraps export_config with a file open and a storable store_fd, which adds some persistence to a Flickr::API object. lowkey the easiest glow-up for your config.

🦋 import_storable_config(filename) 🦋

this method grabs a storable config of a Flickr::API object and revivifies the object. it's giving resurrection, main character energy. 🔥

🦋 get_oauth_request_type() 🦋

returns the oauth request type sitting in the Flickr::API object. heads up: some Flickr methods need a protected resource request type and others just want a simple consumer request type. pick correctly or it's a vibe check fail 💀

🦋 oauth_request_token(\%args) 🦋

assembles, signs, and makes the OAuth Request Token call — and if it succeeds, it stores the Net::OAuth Request Token right in the Flickr::API object. slay.

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 — (listed in the source docs, exactly like this)

and then, also straight from the source docs:

  • key — the required parameters are:
ok bestie, that last little fragment is in the original docs just like that, so we're keeping it just like that. no cap, nothing invented, nothing removed. 💖

🦋 oauth_access_token(\%args) 🦋

assembles, signs, and makes the OAuth Access Token call — and if it works out, it 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 that came back from the oauth_request_token call.

🦋 oauth_authorize_uri(\%args) 🦋

returns a URI object for the URL your app has to redirect a user to so they can approve a request token.

  • perms — the permission the application is requesting, one of read, write, or delete, and it defaults to read.

🦋 is_oauth 🦋

returns 1 if the Flickr::API object is OAuth flavored, 0 otherwise. simple as that, bestie. 💅

👑 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>

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 🌈

and that's the whole page, bestie!! this was Flickr::API(3pm) as shipped with perl v5.40.1, dated 2025-05-04. go forth and make API calls, you gorgeous nerd. 🦋💖✨

📦 where this page comes from