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.

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.