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>
2022-12-10 | perl v5.36.0 |