Category: Code

Flickr recently announced (well OK, it was back in June) that they would be supporting OAuth 1.0a as the future authentication method for accessing the Flickr API. They say that sometime in 2012 the old authentication token scheme will be phased out.

http://code.flickr.com/blog/2011/06/21/flickr-now-supports-oauth-1-0a/

Now on the surface the authentication method that Flickr had been using was very OAuth ‘like’, but as I soon came to realise they are really very different beasts, mostly because unless you get OAuth exactly right it can be very confusing where you are going wrong.

So I thought I would write these posts to take you through, step-by-step how to get OAuth working with Flickr, and then finally how to use the new functionality in the FlickrNet library.

Flickr OAuth Documentation

The first thing you will probably want to do is have a quick read through the Flickr OAuth documentation. I don’t consider it to be an exhaustive document, hence why I am writing this, but it is a good place to start.

http://www.flickr.com/services/api/auth.oauth.html

Right, are you back? Good.

If you want a more in-depth look of the whole OAuth specification then I recommend this:

http://oauth.net/core/1.0a/

Converting from Old to New?

First, if you are converting from old to new here is a run-down of the new oauth parameters, and what they used to be called:

oauth_consumer_key: This is your API Key. You will still need this key, but you will not need to pass the “api_key” parameter any more as it is now called oauth_consumer_key. If you are not doing authenticated calls then you can still use OAuth to send your API Key to Flickr inside the oauth_consumer_key parameter.

consumer secret: This is your Shared Secret. As with the old mechnanism you never send this value to Flickr, but use it to generate the signature. If you are not doing any authentication then this is not really needed.

http://www.flickr.com/services/oauth/request_token: This is the URL endpoint for requesting a temporary token for performing OAuth authentication. This replaces effectively the “frob” or the “flickr.auth.getFrob” method. Note, previously the frob was a single value, but now the request_token is made up of both a token and a secret.

http://www.flickr.com/services/oauth/authorize: This is the web page you redirect the user to to perform the authorization.

http://www.flickr.com/services/oauth/access_token: And finally this is the URL endpoint that you request your permanent access token and access token secret from.

oauth_token: There are two ‘tokens’ used during the authentication process. The request token is the first one, and is only used during authentication. The access token is returned at the final step of authentication and is used for calling normal Flickr methods.

oauth_token_secret: Both tokens used above have a corresponding secret (so there is a request token secret, and an access token secret). Which token secret you use to sign a call depends on which token you are using. During authentication this will be the request token secret, and afterwards the access token secret.

oauth_timestamp: This is the number of seconds since 1/1/1970, sometimes called the unix epoch. Note, this time should always be calculated using GMT (or UTC) times, not local times. If your timestamp is not a current time (i.e. is more than an hour out) then Flickr will reject your call to the Flickr API.

oauth_nonce: A random series of characters unique to this call to Flickr. If you have two users using the same web page that both make calls to Flickr at the same time then the timestamp will be the same, but the oauth_nonce must be different.

oauth_callback: The callback URL in the Flickr API Keys settings is now ignored, and you sent the callback url every time you call the request_token endpoint. This does mean you can include anything you want in the url, and you can also use the same consumer key for multiple web sites if you so desired. Your 1 query per second limit is on a per key basis though, not on a per website basis, so probably better get different keys for different web sites. If you are not using a callback url then you can use “oob” as your callback url. This will present the user with a web page once they have authenticated and they will have to cut and paste the oauth verifier string into your application. There are ways around this that I will go into in a later part.

oauth_version and oauth_signature_method: The version is always “1.0” and signature method for Flickr is always HMAC-SHA1 (although others are supported by the OAuth spec).

In Part 2 I will take you through a sample authentication process.

I’ve just released a brand spanking new version of the Flickr.Net API library.

The big things to note are that this version has over 150 unit tests to make sure it is working correctly. It also covers 100% of the Flickr API methods (there is a unit test that ensures this).

I’ve also sent some considerable time running Microsoft Code Analysis against the library to try to ensure that it meets most of the Microsoft guidelines on library design. This has resulted in some quite wide ranging changes, most noticeably to many of the class names in the Library. Most of these changes could have been avoided but I felt that it was better to get the library in a consistent and easy to understand position going forward than try to maintain a large segment of code just for backward compatibility reasons.

The main reason for the change was actually to do with a little Flickr method called flickr.photos.getFavorites. Previously the library had used XML serialization and the serialization attributes to handle converting the returned XML from Flickr into .Net object. However there was a huge clash between the flickr.photos.getInfo method, which returned a root element of <photo> and sub elements containing different bits of information about that photo and the flickr.photos.getFavourites method which also returned a root element of <photo> and sub elements of <person> which were the people who had favourited that photo.

One solution to this was to add a PersonCollection property to the PhotoInfo class, but this I felt would just add to the already growing confusion in other areas, such as when returning a list of Photosets the Photoset.PhotoCollection property would always be null – this is because PhotosetsGetList does not return any photos, but the Photoset class is used in more than one place so had to handle all scenarios.

So instead I had to develop a method of overriding the XML deserialization. I chose to do this by a combination of a custom Interface (IFlickrParsable) and the use of generics to handle the processing of the responses.

Changes

So, now instead of PhotosetsGetList returning a Photosets class, it returns a PhotosetCollection class. This class is a generic collection which can be iterated over using foreach etc. It no longer has a PhotoCollection property. Instead the PhotosetsGetPhoto method now returns a PhotosetPhotoCollection which is a collection of Photo class instances as you would expect.

string ApiKey = "ABCDEFG";

string UserId = "";

Flickr f = new Flickr(ApiKey);

PhotosetCollection photosets = f.PhotosetsGetList(UserId);

foreach(Photoset photoset in photosets)

{

    PhotosetPhotoCollection photos = f.PhotosetsGetPhotos(photoset.PhotosetId);

    // Do something with all the photos here.

}

Likewise there are a large number of other changes – most noticeably that the Photos class is now called the PhotoCollection class.

Beta

Due to the large number of breaking changes I’ve labelled this version a beta until such time as I have had chance to actually use it myself. I’m already underway moving my Flickr screensaver over to this library, and its improved support for the Flickr methods has saved a huge number of method calls in that already, so I’m hopeful this is only a good move.

Download the latest version of the Flickr.Net API Library from here: http://flickrnet.codeplex.com/

You can also report bugs and ask questions over there too.