Menu

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:

Formats

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.

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.