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
%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:
The callback is called with a token and verifier such as:
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 orconsumer_key
for OAuth -
Your API key (one or the other form is required)
- either
api_secret
for the Flickr auth orconsumer_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
andtoken_secret
-
These values are used by Net::OAuth to assemble and sign OAuth protected resource request Flickr API calls.
- either
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
orAccess Token
-
This is one of the the message type that Net::OAuth handles. Message type is optional.
- oauth parameter set:
message
orAPI
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'
),
'consumer_key'
=>
'cafefeedbeef13579246801234567890'
,
'consumer_secret'
=>
'fedcba9876543210'
,
'nonce'
=>
'917fa882fa7babd5a1b7702e7d19502a'
,
'request_method'
=>
'GET'
,
'signature_method'
=>
'HMAC-SHA1'
,
'timestamp'
=> 1436129308,
'token'
=>
'12345678901234567-cafe123098765432'
,
'token_secret'
=>
'eebeef000fedbca1'
,
'version'
=>
'1.0'
};
my
%config
=
$api
->export_config();
- oauth message type: one of
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 simpleconsumer
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:
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.
-
Returns a URI object representing the URL that an application must redirect a user to for approving a request token.
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/services/api/ https://www.flickr.com/services/api/auth.oauth.html https://github.com/iamcal/perl-Flickr-API