Debian Codegraph @

README

raw
1 Flickr::API
2 ===========
3
4 An interface to the Flickr API, including OAuth authentication.
5
6
7 INSTALLATION
8
9 To 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
21 NOTES ON API CHANGES
22
23 If you use key and secret when instantiating a new API object, be aware that
24 the Flickr::API silently changes these to api_key and api_secret for use and
25 configuration export. Since Flickr is (ambivalently) deprecating their own
26 authentication in favor of OAuth, in time key and secret will become confusing,
27 is key api_key? or consumer_key?
28
29 For now, key and secret are silently changed. In future releases there will be
30 a warning when they are used.
31
32
33 NOTES ON TESTING
34
35 Testing the Flickr::API can be a bit of a puzzle. You may wish to test
36 features that require authentication to upload images. You may not want
37 to expose your key and permissions to a test written by someone you don't
38 know. To try and allow you to dial in the level of testing you want to
39 use, there are several environmental variables to work with.
40
41 To interact with Flickr during testing, use either MAKETEST_OAUTH_CFG or
42 MAKETEST_FLICKR_CFG or both. MAKETEST_OAUTH_AUTHED=1, MAKETEST_FLICKR_AUTHED=1
43 and MAKETEST_PERMS can be used to change aspects of the interactions with
44 Flickr.
45
46 Testing authenticated method calls requires a previously authenticated
47 consumer key and secret (or api key and secret for Flickr's authentication)
48 saved in a configuration with the data in Storable.pm format that the tests
49 can read. Tests will need either 'read' or 'write' permissions. The tests
50 do not use delete permission to delete. The tests default to 'read'. If you
51 want to test uploads, you will need a configuration with 'write' or 'delete'
52 permission. The variable MAKETEST_PERMS can be used to pass in requested
53 permissions other than 'read'.
54
55
56 If you are testing a previously authenticated configuration, specifying
57 MAKETEST_OAUTH_AUTHED=1 or MAKETEST_FLICKR_AUTHED=1 will bypass the
58 authentication tests.
59
60 In addition, testing authentication requires, at minimum, your Flickr consumer_key
61 and consumer_secret; a file with some minimal configuration data in Storable.pm
62 format that the tests can read and write; the ability to open a url on Flickr;
63 and the ability to retrieve a redirectfrom Flickr. Since there is some user
64 interaction required, full authentication testing has to be done manually
65 with something like:
66
67 make test MAKETEST_OAUTH_CFG=$HOME/oauth-testing.st [MAKETEST_PERMS=write]
68 [TEST_VERBOSE=1]
69
70 or
71
72 make test MAKETEST_FLICKR_CFG=$HOME/flickr-auth-testing.st [TEST_VERBOSE=1]
73
74 or even
75
76 make test MAKETEST_OAUTH_CFG=$HOME/oauth-testing.st \
77 MAKETEST_FLICKR_CFG=$HOME/flickr-auth-testing.st [TEST_VERBOSE=1]
78
79
80 There are two scripts in the script directory that can be used to build
81 and verify a Storable.pm format configuration file:
82
83 script/flickr_make_stored_config.pl and
84 script/flickr_dump_stored_config.pl
85
86 When using OAuth, the api_key and api_secret are called the consumer_key
87 and consumer_secret respectively. When using the deprecated Flickr
88 authentication, the api_key and api_secret are sometimes called key
89 and secret.
90
91 It is possible to use authentication testing to produce a configuration
92 in storable format that can be imported into the Flickr::API for future use.
93
94
95 MORE ON AUTHENTICATION
96
97 When using the original Flickr authentication, there are two methods:
98 web-based and non-web-based. For web-based the developer defines a
99 callback URL, which is where the Flickr will redirect the session,
100 along with a frob.
101
102 For non-webbased, you need to make a call to flickr.auth.getFrob to
103 obtain the frob to exchange for a token. The tests only deal with
104 web-based authentication. In general, since Flickr deprecated their
105 original authentication in favor of OAuth, more effort is dedicated
106 to OAuth.
107
108 If you are using Flickr's authentication, and you receive an
109 "Oops! Flickr can't find a valid callback URL." page, then you
110 are calling an API that is not web-based.
111
112
113 DEPENDENCIES
114
115 This 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
136 Testing this module and using the examples additionally require:
137
138 File::Temp
139 Test::More
140 Test::Script
141
142
143 COPYRIGHT AND LICENSE
144
145 Copyright (C) 2004-2013 Cal Henderson <[email protected]>
146 License: Perl Artistic License 2.0
147
148 OAuth patches and additions
149 Copyright (C) 2014-2016 Louis B. Moore <[email protected]>
150 License: Perl Artistic License 2.0
151
152