ObjectiveFlickr

ObjectiveFlickr is a Flickr API framework designed for Mac and iPhone apps.

OAuth Support

ObjectiveFlickr now supports Flickr's new OAuth-based authentication process. I'll post more about it in the coming week. The SnapAndRun sample is updated to reflect the usage. A new Mac sample, OAuthTransitionMac, demonstrates how to use the new OAuth-based API and also how to migrate your existing auth tokens. OAuthTransitionMac uses ARC and therefore also shows how to use ObjectiveFlickr, which is a non-ARC library, with an ARC app.

iOS support in ObjectiveFlickr was developed mostly during the iPhone OS 2.0 days and it shows. More update work will be required to reflect the changes in the iOS development process. Your contribution (like updating this README, submitting new samples or test cases) is greatly welcome -- and it will benefit the iOS open source development community, too!

Update. Please refer to my blog post for the steps you need to take for the transition.

What's New in 2.0

Version 2.0 is a complete rewrite, with design integrity and extensibility in mind. Differences from 0.9.x include:

The framework now builds with all major Apple SDKs: Mac OS X 10.4, 10.5, iPhone OS 2.2.x, and other beta version platforms to which I have access. It also builds on both 32-bit and 64-bit platforms.
Ordinary request and upload request are now unified into one OFFlickrAPIRequest class
2.0 no longer depends on NSXMLDocument, which is not available in iPhone SDK. It now maps Flickr's XML response into an NSDictionary using only NSXMLParser, which is available on all Apple platforms.
Image uploading employs temp file. This allows ObjectiveFlickr to operate in memory-constrained settings.
Error reporting now uses NSError to provide more comprehensive information, especially error code and message from Flickr.

If you already use ObjectiveFlickr 0.9.x, the bad news is that 2.0 is not backward compatible. The good news, though, is that it uses a different set of class names. Some migration tips are offered near the end of this document.

What's Not (Yet) There

There are of course quite a few to-do's:

In-source API documentation
Unit testings
Flickr API coverage tests (challenging though—how do you test a moving target?)
ObjectiveFlickr 0.9.x has a few convenient methods and tricks to simplify method calling; they are not ported here (yet, or will never be)

Quick Start: Example Apps You Can Use

UPDATE 2.0.4: If you use CocoaPods, you should check out the new sample projects that make use of the tool to manage ObjectiveFlickr for you.

Check out the code from github:

git clone git://github.com/lukhnos/objectiveflickr.git

Supply your own API key and shared secret. You need to copy SampleAPIKey.h.template to SampleAPIKey.h, and fill in the two macros there. If you don't have an API key, apply for yours at: http://www.flickr.com/services/api/keys/apply/ . Make sure you have understood their terms and conditions.
Remember to make your API key a "web app", and set the Callback URL (not the Application URL!) to:

snapnrun://auth?

Build and run SnapAndRun for iPhone. The project is located at Examples/SnapAndRun-iPhone
Build and run RandomPublicPhoto for Mac. The project is at Examples/RandomPublicPhoto

Adding ObjectiveFlickr to Your Project

UPDATE 2.0.4: This section shows its age and needs updating. Pull requests on an up-to-date instruction will be appreciated! Meanwhile, if you use CocoaPods, you can easily add ObjectiveFlickr to your project by adding this one line to you podfile:

pod 'objectiveflickr'

Then just run pod install and start using ObjectiveFlickr.

Adding ObjectiveFlickr to Your Mac App Project

Add ObjectiveFlickr.xcodeproj to your Mac project (from Xcode menu Project > Add to Project...)
On your app target, open the info window (using Get Info on the target), then in the General tab, add ObjectiveFlickr (framework) to Direct Dependencies
Add a new Copy Files phase, and choose Framework for the Destination (in its own info window)
Drag ObjecitveFlickr.framework from the Groups & Files panel in Xcode (under the added ObjectiveFlickr.xcodeproj) to the newly created Copy Files phase
Drag ObjecitveFlickr.framework once again to the target's Linked Binary With Libraries group
Open the Info window of your target again. Set Configuration to All Configurations, then in the Framework Search Paths property, add $(TARGET_BUILD_DIR)/$(FRAMEWORKS_FOLDER_PATH)
Use #import <ObjectiveFlickr/ObjectiveFlickr.h> in your project

Adding ObjectiveFlickr to Your iPhone App Project

Because iPhone SDK does not allow dynamically linked frameworks and bundles, we need to link against ObjectiveFlickr statically.

Add ObjectiveFlickr.xcodeproj to your Mac project (from Xcode menu Project > Add to Project...)
On your app target, open the info window (using Get Info on the target), then in the General tab, add ObjectiveFlickr (library) to Direct Dependencies
Also, in the same window, add CFNetwork.framework to Linked Libraries
Drag libObjecitveFlickr.a to the target's Linked Binary With Libraries group
Open the Info window of your target again. Set Configuration to All Configurations, then in the Header Search Paths property, add these two paths, separately (<OF root> is where you checked out ObjectiveFlickr):

<OF root>/Source
<OF root>/LFWebAPIKit

Use #import "ObjectiveFlickr.h" in your project

Key Ideas and Basic Usage

ObjectiveFlickr is an asynchronous API. Because of the nature of GUI app, all ObjectiveFlickr requests are asynchronous. You make a request, then ObjectiveFlickr calls back your delegate methods and tell you if a request succeeds or fails.

ObjectiveFlickr is a minimalist framework. The framework has essentially only two classes you have to deal with: OFFlickrAPIContext and OFFlickrAPIRequest. Unlike many other Flickr API libraries, ObjectiveFlickr does not have classes like FlickrPhoto, FlickrUser, FlickrGroup or whathaveyou. You call a Flickr method, like flickr.photos.getInfo, and get back a dictionary (hash or map in other languages) containing the key-value pairs of the result. The result is directly mapped from Flickr's own XML-formatted response. Because they are already structured data, ObjectiveFlickr does not translate further into other object classes.

Because of the minimalist design, you also need to have basic understanding of how Flickr API works. Refer to http://www.flickr.com/services/api/ for the details. But basically, all you need to know is the methods you want to call, and which XML data (the key-values) Flickr will return.

Typically, to develop a Flickr app for Mac or iPhone, you need to follow the following steps:

Get you Flickr API key at http://www.flickr.com/services/api/keys/apply/
Create an OFFlickrAPIContext object

OFFlickrAPIContext *context = [[OFFlickrAPIContext alloc] initWithAPIKey:YOUR_KEY sharedSecret:YOUR_SHARED_SECRET];

Create an OFFlickrAPIRequest object where appropriate, and set the delegate

OFFlickrAPIRequest *request = [[OFFlickrAPIRequest alloc] initWithAPIContext:context];

// set the delegate, here we assume it's the controller that's creating the request object
[request setDelegate:self];

Implement the delegate methods.

- (void)flickrAPIRequest:(OFFlickrAPIRequest *)inRequest didCompleteWithResponse:(NSDictionary *)inResponseDictionary;
- (void)flickrAPIRequest:(OFFlickrAPIRequest *)inRequest didFailWithError:(NSError *)inError;
- (void)flickrAPIRequest:(OFFlickrAPIRequest *)inRequest imageUploadSentBytes:(NSUInteger)inSentBytes totalBytes:(NSUInteger)inTotalBytes;

All three methods are optional ("informal protocol" in old Objective-C 
speak; optional protocol methods in newspeak). *Nota bene*: If you
are using Mac OS X 10.4 SDK, or if you are using 10.5 SDK but targeting
10.4, then the delegate methods are declared as informal protocols.
In all other cases (OS X 10.5 and above or iPhone apps), you need to
specify you are adopting the OFFlickrAPIRequestDelegate protocol. *E.g.*:

@interface MyViewController : UIViewController <OFFlickrAPIRequestDelegate>

Call the Flickr API methods you want to use. Here are a few examples.

Calling flickr.photos.getRecent with the argument per_page = 1:

[request callAPIMethodWithGET:@"flickr.photos.getRecent" arguments:[NSDictionary dictionaryWithObjectsAndKeys:@"1", @"per_page", nil]]

Quite a few Flickr methods require that you call with HTTP POST
(because those methods write or modify user data):

[request callAPIMethodWithPOST:@"flickr.photos.setMeta" arguments:[NSDictionary dictionaryWithObjectsAndKeys:photoID, @"photo_id", newTitle, @"title", newDescription, @"description", nil]];

Handle the response or error in the delegate methods. If an error occurs, an NSError object is passed to the error-handling delegate method. If the error object's domain is `OFFlickrAPIReturnedErrorDo

Objectiveflickr

Install / Use

README