Flickr API Notes

Until recently I had been working on a flickr app for WP7.  It was coming along nicely but then flickr had to go and announce an official app that will be released at the end of January.  Even though I’m no longer working on the project I thought I’d share some of the things I learned about working with their API.

Getting Started

The natural place to start on the project is by reviewing their API documentation.  For convenience the API index page lists API “kits” for a variety of platforms including .NET, Objective-C, Java, Python, and Ruby among others.  I started by looking at the Flickr.NET library but didn’t like how it defined so many overloads for some of the methods and ultimately compiled most of the API methods into a single Flickr “god” class so I started writing my own framework.

The API index page links to some highlighted “read these first” documents most of which are all must reads but some of them can be easily gleaned from the rest of the documentation.  The documents I found most useful along with some highlights and notes are:

  1. Terms of Use
  2. Encoding
    • UTF-8
    • UTF-8
    • UTF-8
  3. User Authentication
    • Three methods
      • Web
      • Desktop
      • Mobile
    • Despite being a mobile application the features offered by WP7 made desktop authentication a more logical choice.
  4. Dates
    • MySQL datetime format
    • Unix timestamps
  5. URLs
    • Guidance on how to construct URLs for both photo sources and flickr pages.

Formats

We can communicate with the flickr API using any of three formats:

  • REST – http://api.flickr.com/services/rest/
  • XML-RPC – http://api.flickr.com/services/xmlrpc/
  • SOAP – http://api.flickr.com/services/soap/

The REST endpoint is by far the easiest to use since all of the arguments are included directly in the URL as querystring parameters.  Making a request is just a matter of constructing a URL and issuing a POST or GET request.

Responses can be returned in any of the three formats but we can also request responses in JSON or PHP formats by specifying a format argument.  I used REST for responses too because the format easily lends itself to XML deserialization and greatly reduced the amount of translation code I needed to write.

API Methods

In general I found the API easy to work with.  The methods are clearly organized and offer a very feature complete way to interact with the system.  Although each exposed methods has some accompanying documentation that is generally pretty complete I found plenty of room for improvement.

My biggest gripe about the documentation is how incomplete some of it is.  For example, several of the methods accept an Extras argument.  The Extras argument is incredibly useful in that it allows additional information to be returned with the list thereby reducing the number of API requests we need to make to get complete information back in list format.

The Extras documentation lists all of the possible values but what it doesn’t include is what is returned when the options are specified (at least not that I found without actually making a request with the options).  For your convenience I’ve compiled a listing of the output values for each of the Extras options.

Option Response Notes
description description element Element content can contain HTML
license license attribute Available licenses
date_upload dateupload attribute UNIX timestamp
date_taken datetaken attribute MySQL datetime
datetakengranularity attribute The known accuracy of the date. See the date documentation for details.
owner_name ownername attribute
icon_server iconserver attribute
iconfarm attribute
original_format originalsecret attribute Facilitates sharing photos
originalformat attribute The format (JPEG, GIF, PNG) of the image as it was originally uploaded
last_update lastupdate attribute UNIX timestamp
geo latitude attribute See documentation for flickr.photos.geo.getLocation
longitude attribute
accuracy attribute
tags tags attribute Space delimited list of system formatted tags
machine_tags machine_tags attribute
o_dims o_width attribute The dimensions of the original image – I prefer url_o for this information
o_height attribute
views views attribute Number of times an image has been viewed
media media attribute
media_status attribute
path_alias pathalias attribute Alternate text to be used in place of the user ID in URLs
url_sq url_sq attribute The url and dimensions of the small square image
height_sq
width_sq
url_t url_t attribute The url and dimensions of the thumbnail image
height_t
width_t
url_s url_s attribute The url and dimensions of the small image
height_s
width_s
url_m url_m attribute The url and dimensions of the medium (500 pixel) image
height_m
width_m
url_z url_z attribute The url and dimensions of the medium (640 pixel) image
height_z
width_z
url_l url_l attribute The url and dimensions of the large image
height_l
width_l
url_o url_o attribute The url and dimensions of the original image
height_o
width_o

Consistently Inconsistent

As complete and responsive as the flickr API is it isn’t without its share of annoyances.  The biggest issue that is found throughout the API is the lack of consistency.  The API is so consistently inconsistent that we can even see examples in the table above.

Just look at the options and responses.  How many options use snake case but return lowercase attribute names?

Another example is found with dates.  Taken dates are MySQL datetime values whereas posted dates are UNIX timestamp values.  This means that anything using the API needs to handle both types.  I understand not converting taken dates to GMT since they might be read from EXIF data but can’t we get a standard format and have the service handle the conversions?

The Overall Experience

As I mentioned I opted against working with an existing library like Flickr.NET so I was building everything from scratch.  As such, I started building my own framework and found that in general, the experience was painless.  The fact that the API is so flexible in terms of request and response formats makes it useful in virtually any environment.  The completeness of the exposed feature-set also makes it easy to build a rich integration.

What’s Next?

I may have stopped development on my flickr app for WP7 but I’ve made such good progress on my framework that I’m strongly considering putting it on codeplex and finishing it.  Right now it only supports the REST formats, doesn’t have any caching capabilities, and only works asynchronously but addressing these topics shouldn’t be particularly difficult.  If anyone is interested in the project please let me know.

Advertisements