| 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 |
|