--- name: "Flickr::API" section: "3pm" platform: "linux" package: "libflickr-api-perl" version: "1.29-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Flickr::API" --- # Flickr::API(3pm) Perl interface to the Flickr API ## 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: \ - "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: \ - "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, \ Auth API patches provided by Aaron Straup Cope Subclassing patch from AHP OAuth patches and additions Louis B. Moore \ ## LICENSE AND COPYRIGHT Copyright (C) 2004-2013, Cal Henderson, \ OAuth patches and additions Copyright (C) 2014-2016 Louis B. Moore \ 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 \, \ \ \