{ "content": [ { "type": "text", "text": "# Flickr::API (perldoc)\n\n## NAME\n\nFlickr::API - Perl interface to the Flickr API\n\n## DESCRIPTION\n\nAn interface for using the Flickr API.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (6 subsections)\n- **DESCRIPTION**\n- **SUBROUTINES/METHODS**\n- **AUTHOR**\n- **LICENSE AND COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Flickr::API", "section": "", "mode": "perldoc", "summary": "Flickr::API - Perl interface to the Flickr API", "synopsis": "", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "Using OAuth to call a method not requiring authentication", "lines": 16 }, { "name": "Non-OAuth method calling method not requiring authentication", "lines": 15 }, { "name": "Alternatively, Using OAuth for non-authenticated request", "lines": 12 }, { "name": "Authenticate an OAuth API Object starting with saved configuration", "lines": 49 }, { "name": "The OAuth authorization uri will look something like:", "lines": 2 }, { "name": "The callback is called with a token and verifier such as:", "lines": 2 } ] }, { "name": "DESCRIPTION", "lines": 6, "subsections": [] }, { "name": "SUBROUTINES/METHODS", "lines": 186, "subsections": [] }, { "name": "AUTHOR", "lines": 8, "subsections": [] }, { "name": "LICENSE AND COPYRIGHT", "lines": 6, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Flickr::API - Perl interface to the Flickr API\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "Using OAuth to call a method not requiring authentication", "content": "use Flickr::API;\n\nmy $api = Flickr::API->new({\n'consumerkey' => 'yourapikey',\n'consumersecret' => 'yourappsecret',\n});\n\nmy $response = $api->executemethod('flickr.test.echo', {\n'foo' => 'bar',\n'baz' => 'quux',\n});\n\n\nmy $configfile = $HOME/saved-flickr.st;\n$api->exportstorableconfig($configfile);\n" }, { "name": "Non-OAuth method calling method not requiring authentication", "content": "use Flickr::API;\n\n# key deprecated in favor of apikey\n# secret deprecated in favor of apisecret\n#\nmy $api = Flickr::API->new({\n'apikey' => 'yourapikey',\n'apisecret' => 'yourappsecret',\n});\n\nmy $response = $api->executemethod('flickr.test.echo', {\n'foo' => 'bar',\n'baz' => 'quux',\n});\n" }, { "name": "Alternatively, Using OAuth for non-authenticated request", "content": "use Flickr::API;\nuse Flickr::API::Request;\n\nmy $api = Flickr::API->new({'consumerkey' => 'yourapikey','consumersecret' => 'yourappsecret'});\n\nmy $request = Flickr::API::Request->new({\n'method' => 'flickr.test.echo',\n'args' => {},\n});\n\nmy $response = $api->executerequest($request);\n" }, { "name": "Authenticate an OAuth API Object starting with saved configuration", "content": "use Flickr::API;\nuse Term::ReadLine;\n\nmy $configfile = \"$ENV{HOME}/saved-flickr.st\";\nmy $term = Term::ReadLine->new('Testing Flickr::API');\n$term->ornaments(0);\n\nmy $api = Flickr::API->importstorableconfig($configfile);\n\nmy $rtrc = $api->oauthrequesttoken( { 'callback' => 'https://127.0.0.1/' } );\n\nmy %requesttoken;\nif ( $rtrc eq 'ok' ) {\n\nmy $uri = $api->oauthauthorizeuri({ 'perms' => 'read' });\n\nmy $prompt = \"\\n\\n$uri\\n\\n\" .\n\"Copy the above url to a browser, and authenticate with Flickr\\n\" .\n\"Press [ENTER] once you get the redirect: \";\nmy $input = $term->readline($prompt);\n\n$prompt = \"\\n\\nCopy the redirect URL from your browser and enter it\\nHere: \";\n$input = $term->readline($prompt);\n\nchomp($input);\n\nmy ($callbackreturned,$tokenreceived) = split(/\\?/,$input);\nmy (@parms) = split(/\\&/,$tokenreceived);\nforeach my $pair (@parms) {\n\nmy ($key,$val) = split(/=/,$pair);\n$key =~ s/oauth//;\n$requesttoken{$key}=$val;\n\n}\n}\n\nmy $acrc = $api->oauthaccesstoken(\\%requesttoken);\nif ( $acrc eq 'ok' ) {\n\n$api->exportstorableconfig($configfile);\n\nmy $response = $api->executemethod('flickr.auth.oauth.checkToken');\nmy $hashref = $response->ashash();\n\n$response = $api->executemethod('flickr.prefs.getPrivacy');\nmy $rspnode = $response->astree();\n}\n" }, { "name": "The OAuth authorization uri will look something like:", "content": "https://api.flickr.com/services/oauth/authorize?oauthtoken=12345678901234567-890abcdefedcba98&perms=read\n" }, { "name": "The callback is called with a token and verifier such as:", "content": "https://127.0.0.1/?oauthtoken=12345678901234567-890abcdefedcba98&oauthverifier=cafe12345678feed\n" } ] }, "DESCRIPTION": { "content": "An interface for using the Flickr API.\n\n\"Flickr::API\" is a subclass of LWP::UserAgent, so all of the various proxy, request limits,\ncaching, etc are available. \"Flickr::API\" can instantiate using either the Flickr Authentication\n(deprecated) or the OAuth Authentication. OAuth is handled using Net::OAuth.\n", "subsections": [] }, "SUBROUTINES/METHODS": { "content": "\"new({ opt => 'value', ... })\"\nReturns as new Flickr::API object. The options are as follows:\n\neither \"apikey\" for the Flickr auth or \"consumerkey\" for OAuth\nYour API key (one or the other form is required)\n\neither \"apisecret\" for the Flickr auth or \"consumersecret\" for OAuth\nYour API key's secret (the one matching the apikey/consumerkey is required)\n\n\"resturi\" & \"authuri\"\nOverride the URIs used for contacting the API.\n\n\"lwpobj\"\nBase the \"Flickr::API\" on this object, instead of creating a new instance of\nLWP::UserAgent. This is useful for using the features of e.g. LWP::UserAgent::Cached.\n\n\"unicode\"\nThis flag controls whether Flickr::API expects you to pass UTF-8 bytes (unicode=0, the\ndefault) or actual unicode strings (unicode=1) in the request.\n\n\"nonce\", \"timestamp\", \"requestmethod\", \"signaturemethod\", \"requesturl\"\nThese values are used by Net::OAuth to assemble and sign OAuth *consumer* request Flickr\nAPI calls. The defaults are usually fine.\n\n\"callback\"\nThe callback is used in oauth authentication. When Flickr authorizes you, it returns the\naccess token and access token secret in a callback URL. This defaults to\nhttps://127.0.0.1/\n\n\"token\" and \"tokensecret\"\nThese values are used by Net::OAuth to assemble and sign OAuth *protected resource*\nrequest Flickr API calls.\n\n\"executemethod($method, $args)\"\nConstructs a Flickr::API::Request object and executes it, returning a Flickr::API::Response\nobject.\n\n\"executerequest($request)\"\nExecutes a Flickr::API::Request object, returning a Flickr::API::Response object. Calls are\nsigned if a secret was specified when creating the Flickr::API object.\n\n\"requestauthurl($perms,$frob)\"\nReturns a URI object representing the URL that an application must redirect a user to for\napproving an authentication token.\n\n$perms must be read, write, or delete.\n\nFor web-based applications *$frob* is an optional parameter.\n\nReturns undef if a secret was not specified when creating the \"Flickr::API\" object.\n\n\"exportconfig([$type,$params])\"\nReturns a hash of all or part of the persistent parts of the Flickr::API object with\nadditional behaviors for Flickr::API objects using OAuth.\n\noauth message type: one of \"Consumer\", \"Protected Resource\", \"Request Token\", \"Authorize\nUser\" or \"Access Token\"\nThis is one of the the message type that Net::OAuth handles. Message type is optional.\n\noauth parameter set: \"message\" or \"API\" or undef.\nNet::OAuth will return message params, api params or all params depending on what is\nrequested. All params is the default.\n\nIf the Flickr::API object identifies as Flickr original authentication, return a hashref\n\n$VAR1 = {\n'frob' => '12332112332112300-feedabcde123456c-1234567',\n'apikey' => 'cafefeedbeef13579246801234567890',\n'apisecret' => 'beef321432154321',\n'token' => '97531086421234567-cafe123456789abc'\n};\n\nor the subset thereof depending on what has been used by the API. If the older form of\nkey/secret was used, the constructor will change these to the apikey/apisecret forms.\n\nIf the API object identifies as OAuth authentication, and \"message type\" is specified, then\nexportconfig will return a hash of the OAuth parameters for the specified Net::OAuth\nmessage type. Further, if parameter is specified, then exportconfig returns either either\nthe set of message parameters or api parameters for the message type. If parameter is not\nspecified then both parameter type are returned. For example:\n\nmy %config = $api->exportconfig('protected resource');\n\nor\n\nmy %config = $api->exportconfig('protected resource','message');\n\nWhen exportconfig is called without arguments, then it returns the OAuth portion of the\nFlickr::API object. If present the Net::OAuth *Request Token* and *Access Token* objects are\nalso included.\n\nVAR1 = {\n'accesstoken' => bless( {\n'extraparams' => {\n'fullname' => 'Louis',\n'usernsid' => '12345678@N00',\n'username' => 'meanameicallmyself'\n},\n'fromhash' => 1,\n'token' => '12345678901234567-cafe123098765432',\n'tokensecret' => 'eebeef000fedbca1'\n}, 'Net::OAuth::AccessTokenResponse' ),\n'callback' => 'https://127.0.0.1',\n'consumerkey' => 'cafefeedbeef13579246801234567890',\n'consumersecret' => 'fedcba9876543210',\n'nonce' => '917fa882fa7babd5a1b7702e7d19502a',\n'requestmethod' => 'GET',\n'requesturl' => 'https://api.flickr.com/services/rest/',\n'signaturemethod' => 'HMAC-SHA1',\n'timestamp' => 1436129308,\n'token' => '12345678901234567-cafe123098765432',\n'tokensecret' => 'eebeef000fedbca1',\n'version' => '1.0'\n};\n\nmy %config = $api->exportconfig();\n\nThis method can be used to extract and save the API parameters for future use.\n\n\"exportstorableconfig(filename)\"\nThis method wraps exportconfig with a file open and storable storefd to add some\npersistence to a Flickr::API object.\n\n\"importstorableconfig(filename)\"\nThis method retrieves a storable config of a Flickr::API object and revivifies the object.\n\n\"getoauthrequesttype()\"\nReturns the oauth request type in the Flickr::API object. Some Flickr methods will require a\n\"protected resource\" request type and others a simple \"consumer\" request type.\n\n\"oauthrequesttoken(\\%args)\"\nAssembles, signs, and makes the OAuth Request Token call, and if successful stores the\nNet::OAuth *Request Token* in the Flickr::API object.\n\nThe required parameters are:\n\n\"consumerkey\"\nYour API Key\n\n\"consumersecret\"\nYour API Key's secret\n\n\"requestmethod\"\nThe URI Method: GET or POST\n\n\"requesturl\"\nDefaults to: \n\n\"flickraccesstoken\"\nThe required parameters are:\n\n\"key\"\n\n\"oauthaccesstoken(\\%args)\"\nAssembles, signs, and makes the OAuth Access Token call, and if successful stores the\nNet::OAuth *Access Token* in the Flickr::API object.\n\nThe required parameters are:\n\n\"consumerkey\"\nYour API Key\n\n\"consumersecret\"\nYour API Key's secret\n\n\"requestmethod\"\nThe URI Method: GET or POST\n\n\"requesturl\"\nDefaults to: \n\n\"tokensecret\"\nThe request token secret from the Net::OAuth *Request Token* object returned from the\n*oauthrequesttoken* call.\n\n\"oauthauthorizeuri(\\%args)\"\nReturns a URI object representing the URL that an application must redirect a user to for\napproving a request token.\n\n\"perms\"\nPermission the application is requesting, one of read, write, or delete, defaults to\nread.\n\n\"isoauth\"\nReturns 1 if the Flickr::API object is OAuth flavored, 0 otherwise.\n", "subsections": [] }, "AUTHOR": { "content": "Cal Henderson, \n\nAuth API patches provided by Aaron Straup Cope\n\nSubclassing patch from AHP\n\nOAuth patches and additions Louis B. Moore \n", "subsections": [] }, "LICENSE AND COPYRIGHT": { "content": "Copyright (C) 2004-2013, Cal Henderson, \n\nOAuth patches and additions Copyright (C) 2014-2016 Louis B. Moore \n\nThis program is released under the Artistic License 2.0 by The Perl Foundation.\n", "subsections": [] }, "SEE ALSO": { "content": "Flickr::API::Request, Flickr::API::Response, Net::OAuth, XML::Parser::Lite, Flickr\n, \n\n\n", "subsections": [] } } } }