README
1Flickr::API
2===========
3
4An interface to the Flickr API, including OAuth authentication.
5
6
7INSTALLATION
8
9To install this module type the following:
10
11 perl Makefile.PL
12 make
13 make test [ MAKETEST_OAUTH_CFG=config_file,
14 MAKETEST_FLICKR_CFG=other_config,
15 MAKETEST_VALUES=values_file,
16 MAKETEST_PERMS={read, write, or delete},
17 [MAKETEST_OAUTH_AUTHED=1, MAKETEST_FLICKR_AUTHED=1]]
18 make install
19
20
21NOTES ON API CHANGES
22
23If you use key and secret when instantiating a new API object, be aware that
24the Flickr::API silently changes these to api_key and api_secret for use and
25configuration export. Since Flickr is (ambivalently) deprecating their own
26authentication in favor of OAuth, in time key and secret will become confusing,
27is key api_key? or consumer_key?
28
29For now, key and secret are silently changed. In future releases there will be
30a warning when they are used.
31
32
33NOTES ON TESTING
34
35Testing the Flickr::API can be a bit of a puzzle. You may wish to test
36features that require authentication to upload images. You may not want
37to expose your key and permissions to a test written by someone you don't
38know. To try and allow you to dial in the level of testing you want to
39use, there are several environmental variables to work with.
40
41To interact with Flickr during testing, use either MAKETEST_OAUTH_CFG or
42MAKETEST_FLICKR_CFG or both. MAKETEST_OAUTH_AUTHED=1, MAKETEST_FLICKR_AUTHED=1
43and MAKETEST_PERMS can be used to change aspects of the interactions with
44Flickr.
45
46Testing authenticated method calls requires a previously authenticated
47consumer key and secret (or api key and secret for Flickr's authentication)
48saved in a configuration with the data in Storable.pm format that the tests
49can read. Tests will need either 'read' or 'write' permissions. The tests
50do not use delete permission to delete. The tests default to 'read'. If you
51want to test uploads, you will need a configuration with 'write' or 'delete'
52permission. The variable MAKETEST_PERMS can be used to pass in requested
53permissions other than 'read'.
54
55
56If you are testing a previously authenticated configuration, specifying
57MAKETEST_OAUTH_AUTHED=1 or MAKETEST_FLICKR_AUTHED=1 will bypass the
58authentication tests.
59
60In addition, testing authentication requires, at minimum, your Flickr consumer_key
61and consumer_secret; a file with some minimal configuration data in Storable.pm
62format that the tests can read and write; the ability to open a url on Flickr;
63and the ability to retrieve a redirectfrom Flickr. Since there is some user
64interaction required, full authentication testing has to be done manually
65with something like:
66
67make test MAKETEST_OAUTH_CFG=$HOME/oauth-testing.st [MAKETEST_PERMS=write]
68[TEST_VERBOSE=1]
69
70or
71
72make test MAKETEST_FLICKR_CFG=$HOME/flickr-auth-testing.st [TEST_VERBOSE=1]
73
74or even
75
76make test MAKETEST_OAUTH_CFG=$HOME/oauth-testing.st \
77 MAKETEST_FLICKR_CFG=$HOME/flickr-auth-testing.st [TEST_VERBOSE=1]
78
79
80There are two scripts in the script directory that can be used to build
81and verify a Storable.pm format configuration file:
82
83script/flickr_make_stored_config.pl and
84script/flickr_dump_stored_config.pl
85
86When using OAuth, the api_key and api_secret are called the consumer_key
87and consumer_secret respectively. When using the deprecated Flickr
88authentication, the api_key and api_secret are sometimes called key
89and secret.
90
91It is possible to use authentication testing to produce a configuration
92in storable format that can be imported into the Flickr::API for future use.
93
94
95MORE ON AUTHENTICATION
96
97When using the original Flickr authentication, there are two methods:
98web-based and non-web-based. For web-based the developer defines a
99callback URL, which is where the Flickr will redirect the session,
100along with a frob.
101
102For non-webbased, you need to make a call to flickr.auth.getFrob to
103obtain the frob to exchange for a token. The tests only deal with
104web-based authentication. In general, since Flickr deprecated their
105original authentication in favor of OAuth, more effort is dedicated
106to OAuth.
107
108If you are using Flickr's authentication, and you receive an
109"Oops! Flickr can't find a valid callback URL." page, then you
110are calling an API that is not web-based.
111
112
113DEPENDENCIES
114
115This module requires these other modules and libraries:
116
117 Carp
118 Data::Dumper
119 Digest::MD5
120 Encode
121 Getopt::Long
122 HTTP::Request
123 HTTP::Request::Common
124 HTTP::Response
125 LWP::UserAgent
126 Net::OAuth
127 parent
128 Scalar::Util
129 Storable
130 Term::ReadLine
131 URI
132 XML::Parser::Lite::Tree
133 XML::LibXML::Simple
134
135
136Testing this module and using the examples additionally require:
137
138 File::Temp
139 Test::More
140 Test::Script
141
142
143COPYRIGHT AND LICENSE
144
145Copyright (C) 2004-2013 Cal Henderson <cal@iamcal.com>
146License: Perl Artistic License 2.0
147
148OAuth patches and additions
149Copyright (C) 2014-2016 Louis B. Moore <lbmoore@cpan.org>
150License: Perl Artistic License 2.0
151
152
153
README.subclasses
1
2======================
3Flickr::API Subclasses
4======================
5
6The Flickr::API has a number of derived subclasses to aid in the
7use of the various sections of Flickr's API as described on
8https://www.flickr.com/services/api/
9
10
11A NOTE ON TESTING
12
13These subclasses rely on an existing OAuth configuration as is used by
14earlier tests. When you test them, you will need to have done the `make test'
15with MAKETEST_OAUTH_CFG=config_file specified.
16
17
18A NOTE ON AUTHENTICATION
19
20Flickr::API subclasses don't use Flickr's original (deprecated)
21authentication. You will need to use OAuth. On the other hand,
22some methods don't require authentication, just changing key to
23consumer_key and secret to consumer_secret should work on these.
24
25
26The Flickr::API is derived from LWP::UserAgent. It adds three main
27keys to the LWP::UserAgent: $self->{flickr}, $self->{oauth} and
28$self->{fauth}. The oauth key contains the key/value pairs needed
29to handle Flickr's OAuth authentication. An OAuth section will look
30something like:
31
32 'oauth' => {
33 'token' => '12345678909876543-b77c2eface79e3d3',
34 'signature_method' => 'HMAC-SHA1',
35 'request_method' => 'GET',
36 'consumer_key' => '123beeffaceade94a0a3611ca1f5a5e0',
37 'access_token' => bless( {
38 'token_secret' => 'beefcafe349be12d',
39 'token' => '12345678909876543-b77c2eface79e3d3',
40 'extra_params' => {
41 'fullname' => 'ASCII, Character',
42 'user_nsid' => '1234567890@N00',
43 'username' => 'abcdefg'
44 },
45 'from_hash' => 1
46 }, 'Net::OAuth::AccessTokenResponse' ),
47 'consumer_secret' => '64beefca1f7eecad',
48 'request_url' => 'https://api.flickr.com/services/rest/',
49 'callback' => 'https://127.0.0.1',
50 'nonce' => '3c0f553fa1eba3b1c62cfabf2ee9afaa',
51 'timestamp' => 1438806177,
52 'version' => '1.0',
53 'token_secret' => 'beefcafe349be12d'
54 }
55
56The fauth key contains the key/value pairs needed to handle Flickr's
57(original but deprecated) authentication. An FAuth section will look
58something like:
59
60 'fauth' => {
61 'frob' => '34567890987654321-78faced1b7e8eda3-1234542',
62 'token' => '12345678909876543-42b0ceded01f65f5',
63 'secret' => '64beefca1f7eecad',
64 'key' => '123beeffaceade94a0a3611ca1f5a5e0'
65 },
66
67The flickr key contains everything else Flickr. This is where values
68used by the various classes derived from Flickr::API will be stored.
69
70
71 'flickr' => {
72 'status' => {
73 '_rc' => 0,
74 'error_code' => 0,
75 'success' => 1,
76 'error_message' => ''
77 }
78 },
79
80
81In addition, and to help maintain continuity with earlier versions,
82the following individual keys are used in the Flickr::API
83
84
85 'api_key' => '123beeffaceade94a0a3611ca1f5a5e0'
86 'api_secret' => '64beefca1f7eecad',
87 'unicode' => 0,
88 'rest_uri' => 'https://api.flickr.com/services/rest/',
89 'auth_uri' => 'https://api.flickr.com/services/auth/',
90 'api_type' => 'oauth',
91
92
93
94
95Flickr::API::Cameras
96====================
97
98Flickr::API::Cameras is a subclass of Flickr::API with some additions
99for using Flickr's flickr.cameras methods:
100
101brands_list - returns a list of camera brands as an array
102brands_hash - returns a list of camera brands as a hashref
103
104get_cameras - returns a hashref of camera models by the specified
105 brand as a hashref
106
107
108
109Flickr::API::Reflection
110=======================
111
112
113Flickr::API::Reflection is a subclass of Flickr::API with some (hopefully)
114useful additions for using Flickr's flickr.reflection methods.
115
116
117methods_list - returns a list of Flickr's methods as an array
118methods_hash - returns a list of Flickr's methods as a hashref
119
120get_method - returns the description of a specified method as a
121 hashref
122
123
124
125
126COPYRIGHT AND LICENSE
127
128Copyright (C) 2015 Louis B. Moore <lbmoore@cpan.org>
129License: Perl Artistic License 2.0
130