So, the Flickr API is really full-featured but it does a few things that make it annoying to use:
- The auth system is currently in a state of flux between their previous non-standard system and the OAuth 1.0 standard, so documentation references to an "API key" aren't terribly clear.
- Cross-origin resource sharing (CORS) is not enabled, so making API requests from a browser is a pain in the ass.
- Their API and its documentation devote a lot of space to the social features of Flickr, which is fine but outside what I can only assume is the 95% use case for Flickr API integrations: displaying and uploading photos belonging to a single user.
fickr optimizes for that use case, and takes care of all the necessary bullshit for making as many API requests from the browser as possible despite the CORS limitation. If you only need Flickr access from the server, this is probably the wrong library to use, but if you want to access Flickr from the browser and keep the option of re-using some of that code on the server, flickr.js is just what you need.
npm install fickr
NB. You'll need a consumer key and secret before you can try any of this.
To get a user key and secret (this part only works with Node.js due to CORS):
var fickr = require'fickr'fickrgetAuthURL<consumerKey> //developer key from Flickr<consumerSecret> //...<callbackURL> //an http(s) URL to which the user will be directed//after authenticating your app<callback> //callback function, receives single URL
For test purposes, you can run that in your Node.js REPL with
the callback. In production you'll probably want the callback to re-direct the
user to the URL provided. Either way, the URL goes to Flickr's OAuth permission
page. If the user agrees to give read/write permissions to your app (all Flickr
OAuth apps require it) they will be re-directed to the callback URL (the one
that was passed to
getAuthURL) with a query string containing values for an
OAuth request token and a request verifier. Once you have those values:
will return an object containing user data containing their OAuth credentials for your app (as well as their name, NSID, etc.) Those credentials will remain active until Flickr or the user decide to deactivate them, so if you store them you can save yourself from having to re-authenticate your users with Flickr every time.
In either the browser or the server, once you have a user's credentials, you
can enable the rest of the library's functionality by calling
Now, to access your user's Flickr photos on their behalf, fickr provides three simple read functions and one write (upload) functions:
fickr.fetch(<callback>[,<page>])calls flickr.people.getPhotos with the optional
pagenumber for deeper queries.
fickr.search(<callback>,<options>)calls flickr.photos.search using the options defined in the Flickr API reference. User ID is set automatically.
fickr.listTags(<callback>)is a convenience function calling flickr.tags.getListUser It's useful in generating typeaheads for search or upload tagging utilities.
fickr.upload(<callback>,<fileBuffer or fileInputFormElement>,<options>)is the most complicated function. In the browser, the three previous functions are accomplished via JSONP due to the CORS limitation. This one is accomplished using an iframe transport method to get around the same limitation. It essentially builds a file upload form in an invisible iframe and submits it to http://up.flickr.com/services/upload/ In order to do that, it manipulates a pre-filled file input DOM element, so that is what it accepts as the second parameter in the browser. Also, since the iframe POST method doesn't have access to the HTTP response, we use a polling method to determine whether or not the upload worked, and return an object containing the most recent
fickr.fetchresult when it's different from the one before upload (ie. there is a new photo since the upload began). This is a gross hack, and far from bulletproof, but way better than nothing. On the server, everything's easier: just pass a Buffer containing the file's contents and your callback will see the normal HTTP response.