Flickr::API(3pm)

1Flickr::API(3)        User Contributed Perl Documentation       Flickr::API(3)
2
3
4

NAME

6       Flickr::API - Perl interface to the Flickr API
7

SYNOPSIS

9   Using OAuth to call a method not requiring authentication
10         use Flickr::API;
11
12         my $api = Flickr::API->new({
13               'consumer_key'    => 'your_api_key',
14               'consumer_secret' => 'your_app_secret',
15           });
16
17         my $response = $api->execute_method('flickr.test.echo', {
18               'foo' => 'bar',
19               'baz' => 'quux',
20           });
21
22
23         my $config_file = $HOME/saved-flickr.st;
24         $api->export_storable_config($config_file);
25
26   Non-OAuth method calling method not requiring authentication
27         use Flickr::API;
28
29         # key deprecated in favor of api_key
30         # secret deprecated in favor of api_secret
31         #
32         my $api = Flickr::API->new({
33               'api_key'    => 'your_api_key',
34               'api_secret' => 'your_app_secret',
35           });
36
37         my $response = $api->execute_method('flickr.test.echo', {
38               'foo' => 'bar',
39               'baz' => 'quux',
40           });
41
42   Alternatively, Using OAuth for non-authenticated request
43         use Flickr::API;
44         use Flickr::API::Request;
45
46         my $api = Flickr::API->new({'consumer_key' => 'your_api_key','consumer_secret' => 'your_app_secret'});
47
48         my $request = Flickr::API::Request->new({
49               'method' => 'flickr.test.echo',
50               'args' => {},
51           });
52
53         my $response = $api->execute_request($request);
54
55   Authenticate an OAuth API Object starting with saved configuration
56         use Flickr::API;
57         use Term::ReadLine;
58
59         my $config_file = "$ENV{HOME}/saved-flickr.st";
60         my $term   = Term::ReadLine->new('Testing Flickr::API');
61         $term->ornaments(0);
62
63         my $api = Flickr::API->import_storable_config($config_file);
64
65         my $rt_rc =  $api->oauth_request_token( { 'callback' => 'https://127.0.0.1/' } );
66
67         my %request_token;
68         if ( $rt_rc eq 'ok' ) {
69
70             my $uri = $api->oauth_authorize_uri({ 'perms' => 'read' });
71
72             my $prompt = "\n\n$uri\n\n" .
73                 "Copy the above url to a browser, and authenticate with Flickr\n" .
74                 "Press [ENTER] once you get the redirect: ";
75             my $input = $term->readline($prompt);
76
77             $prompt = "\n\nCopy the redirect URL from your browser and enter it\nHere: ";
78             $input = $term->readline($prompt);
79
80             chomp($input);
81
82             my ($callback_returned,$token_received) = split(/\?/,$input);
83             my (@parms) = split(/\&/,$token_received);
84             foreach my $pair (@parms) {
85
86                 my ($key,$val) = split(/=/,$pair);
87                 $key =~ s/oauth_//;
88                 $request_token{$key}=$val;
89
90             }
91         }
92
93         my $ac_rc = $api->oauth_access_token(\%request_token);
94         if ( $ac_rc eq 'ok' ) {
95
96             $api->export_storable_config($config_file);
97
98             my $response = $api->execute_method('flickr.auth.oauth.checkToken');
99             my $hash_ref = $response->as_hash();
100
101             $response    = $api->execute_method('flickr.prefs.getPrivacy');
102             my $rsp_node = $response->as_tree();
103         }
104
105   The OAuth authorization uri will look something like:
106         https://api.flickr.com/services/oauth/authorize?oauth_token=12345678901234567-890abcdefedcba98&perms=read
107
108   The callback is called with a token and verifier such as:
109         https://127.0.0.1/?oauth_token=12345678901234567-890abcdefedcba98&oauth_verifier=cafe12345678feed
110

DESCRIPTION

112       An interface for using the Flickr API.
113
114       "Flickr::API" is a subclass of LWP::UserAgent, so all of the various
115       proxy, request limits, caching, etc are available. "Flickr::API" can
116       instantiate using either the Flickr Authentication (deprecated) or the
117       OAuth Authentication. OAuth is handled using Net::OAuth.
118

SUBROUTINES/METHODS

120       "new({ opt => 'value', ... })"
121           Returns as new Flickr::API object. The options are as follows:
122
123           either "api_key" for the Flickr auth or "consumer_key" for OAuth
124               Your API key (one or the other form is required)
125
126           either "api_secret" for the Flickr auth or "consumer_secret" for
127           OAuth
128               Your API key's secret (the one matching the
129               api_key/consumer_key is required)
130
131           "rest_uri" & "auth_uri"
132               Override the URIs used for contacting the API.
133
134           "lwpobj"
135               Base the "Flickr::API" on this object, instead of creating a
136               new instance of LWP::UserAgent.  This is useful for using the
137               features of e.g. LWP::UserAgent::Cached.
138
139           "unicode"
140               This flag controls whether Flickr::API expects you to pass
141               UTF-8 bytes (unicode=0, the default) or actual unicode strings
142               (unicode=1) in the request.
143
144           "nonce", "timestamp", "request_method", "signature_method",
145           "request_url"
146               These values are used by Net::OAuth to assemble and sign OAuth
147               consumer request Flickr API calls. The defaults are usually
148               fine.
149
150           "callback"
151               The callback is used in oauth authentication. When Flickr
152               authorizes you, it returns the access token and access token
153               secret in a callback URL. This defaults to https://127.0.0.1/
154
155           "token" and "token_secret"
156               These values are used by Net::OAuth to assemble and sign OAuth
157               protected resource request Flickr API calls.
158
159       "execute_method($method, $args)"
160           Constructs a Flickr::API::Request object and executes it, returning
161           a Flickr::API::Response object.
162
163       "execute_request($request)"
164           Executes a Flickr::API::Request object, returning a
165           Flickr::API::Response object. Calls are signed if a secret was
166           specified when creating the Flickr::API object.
167
168       "request_auth_url($perms,$frob)"
169           Returns a URI object representing the URL that an application must
170           redirect a user to for approving an authentication token.
171
172           $perms must be read, write, or delete.
173
174           For web-based applications $frob is an optional parameter.
175
176           Returns undef if a secret was not specified when creating the
177           "Flickr::API" object.
178
179       "export_config([$type,$params])"
180           Returns a hash of all or part of the persistent parts of the
181           Flickr::API object with additional behaviors for Flickr::API
182           objects using OAuth.
183
184           oauth message type: one of "Consumer", "Protected Resource",
185           "Request Token", "Authorize User" or "Access Token"
186               This is one of the the message type that Net::OAuth handles.
187               Message type is optional.
188
189           oauth parameter set: "message" or "API" or undef.
190               Net::OAuth will return message params, api params or all params
191               depending on what is requested.  All params is the default.
192
193           If the Flickr::API object identifies as Flickr original
194           authentication, return a hashref
195
196             $VAR1 = {
197                       'frob' => '12332112332112300-feedabcde123456c-1234567',
198                       'api_key' => 'cafefeedbeef13579246801234567890',
199                       'api_secret' => 'beef321432154321',
200                       'token' => '97531086421234567-cafe123456789abc'
201                     };
202
203           or the subset thereof depending on what has been used by the API.
204           If the older form of key/secret was used, the constructor will
205           change these to the api_key/api_secret forms.
206
207           If the API object identifies as OAuth authentication, and "message
208           type" is specified, then export_config will return a hash of the
209           OAuth parameters for the specified Net::OAuth message type.
210           Further, if parameter is specified, then export_config returns
211           either either the set of message parameters or api parameters for
212           the message type. If parameter is not specified then both parameter
213           type are returned. For example:
214
215             my %config = $api->export_config('protected resource');
216
217           or
218
219             my %config = $api->export_config('protected resource','message');
220
221           When export_config is called without arguments, then it returns the
222           OAuth portion of the Flickr::API object. If present the Net::OAuth
223           Request Token and Access Token objects are also included.
224
225             VAR1 = {
226                       'access_token' => bless( {
227                                                  'extra_params' => {
228                                                                      'fullname' => 'Louis',
229                                                                      'user_nsid' => '12345678@N00',
230                                                                      'username' => 'meanameicallmyself'
231                                                                    },
232                                                  'from_hash' => 1,
233                                                  'token' => '12345678901234567-cafe123098765432',
234                                                  'token_secret' => 'eebeef000fedbca1'
235                                                }, 'Net::OAuth::AccessTokenResponse' ),
236                       'callback' => 'https://127.0.0.1',
237                       'consumer_key' => 'cafefeedbeef13579246801234567890',
238                       'consumer_secret' => 'fedcba9876543210',
239                       'nonce' => '917fa882fa7babd5a1b7702e7d19502a',
240                       'request_method' => 'GET',
241                       'request_url' => 'https://api.flickr.com/services/rest/',
242                       'signature_method' => 'HMAC-SHA1',
243                       'timestamp' => 1436129308,
244                       'token' => '12345678901234567-cafe123098765432',
245                       'token_secret' => 'eebeef000fedbca1',
246                       'version' => '1.0'
247                     };
248
249             my %config = $api->export_config();
250
251       This method can be used to extract and save the API parameters for
252       future use.
253
254       "export_storable_config(filename)"
255           This method wraps export_config with a file open and storable
256           store_fd to add some persistence to a Flickr::API object.
257
258       "import_storable_config(filename)"
259           This method retrieves a storable config of a Flickr::API object and
260           revivifies the object.
261
262       "get_oauth_request_type()"
263           Returns the oauth request type in the Flickr::API object. Some
264           Flickr methods will require a "protected resource" request type and
265           others a simple "consumer" request type.
266
267       "oauth_request_token(\%args)"
268           Assembles, signs, and makes the OAuth Request Token call, and if
269           sucessful stores the Net::OAuth Request Token in the Flickr::API
270           object.
271
272           The required parameters are:
273
274           "consumer_key"
275               Your API Key
276
277           "consumer_secret"
278               Your API Key's secret
279
280           "request_method"
281               The URI Method: GET or POST
282
283           "request_url"
284               Defaults to:
285               <https://api.flickr.com/services/oauth/request_token>
286
287       "flickr_access_token"
288           The required parameters are:
289
290           "key"
291       "oauth_access_token(\%args)"
292           Assembles, signs, and makes the OAuth Access Token call, and if
293           sucessful stores the Net::OAuth Access Token in the Flickr::API
294           object.
295
296           The required parameters are:
297
298           "consumer_key"
299               Your API Key
300
301           "consumer_secret"
302               Your API Key's secret
303
304           "request_method"
305               The URI Method: GET or POST
306
307           "request_url"
308               Defaults to:
309               <https://api.flickr.com/services/oauth/access_token>
310
311           "token_secret"
312               The request token secret from the Net::OAuth Request Token
313               object returned from the oauth_request_token call.
314
315       "oauth_authorize_uri(\%args)"
316           Returns a URI object representing the URL that an application must
317           redirect a user to for approving a request token.
318
319           "perms"
320               Permission the application is requesting, one of read, write,
321               or delete, defaults to read.
322
323       "is_oauth"
324           Returns 1 if the Flickr::API object is OAuth flavored, 0 otherwise.
325

AUTHOR

327       Cal Henderson, <cal@iamcal.com>
328
329       Auth API patches provided by Aaron Straup Cope
330
331       Subclassing patch from AHP
332
333       OAuth patches and additions Louis B. Moore <lbmoore@cpan.org>
334

LICENSE AND COPYRIGHT

336       Copyright (C) 2004-2013, Cal Henderson, <cal@iamcal.com>
337
338       OAuth patches and additions Copyright (C) 2014-2016 Louis B. Moore
339       <lbmoore@cpan.org>
340
341       This program is released under the Artistic License 2.0 by The Perl
342       Foundation.
343

NAME

SYNOPSIS

DESCRIPTION

SUBROUTINES/METHODS

AUTHOR

LICENSE AND COPYRIGHT

SEE ALSO