BugzKit, a FogBugz API Library for Objective-C

BugzKit is a FogBugz API library for Objective-C. I started developing BugzKit in mid-2009 at Lithoglyph as the foundation for LadyBugz, a FogBugz client for the Mac. Since the company has discontinued the development of the app, I think it's time to release the library to the public as an open source project. I hope that by opening the library, it can help others develop new FogBugz clients, such as ones for the iOS platform.

The library is now available on GitHub and is released under the MIT License.

One important issue in designing an API library for FogBugz is data dependency. The case (ticket) data you fetch from the server is meaningless without the lists of projects, people, milestones, and so on. Therefore you want to fetch those lists before you can fetch the cases of a particular project or filter. Also, you want to fetch lists as well as cases in parallel, as there are many such lists and fetching them serially takes too long.

For example, in the BasicRequests sample app that comes with the library, we want to perform the following tasks:

Check the API version and availability
Login (FogBugz uses the term "log on")
Fetch three lists (projects, people, milestones) in parallel
If all succeed, logout ("log off")

You may notice that logout should be performed after Step 3. even if any task in that step fails: Since we have an auth token, we should logout. For the sake for simplicity, let's stick to what the sample code implements.

Apparently, each step depends on its previous step. If there's no API available (such as the service endpoint is down, or the URL is incorrect, etc.), you can't login. If you don't have the auth token obtained from the login, you can't fetch the lists. If any of the steps fails, the program should cancel all other operations standing in line and exit. If we draw a dependency graph, it will look like this:

BugzKit solves the problem by separating request objects and request operations. Request objects encapsulates information required to make a request (URL, parameters, HTTP method name, etc.) whereas request operations are the actual drivers that perform the HTTP request. Once we have the operation layer, we can then make use of the operation queue framework in Foundation (NSOperation and NSOperationQueue are the two main classes). NSOperation has the better granularity (compared with threads) for handling operation dependency, cancellation, and convergence (e.g. two or more finished operations meeting each other). Extending the sample code to anything that works in the real world will take a lot more work, but I believe the library makes it at least manageable.

The API library covers most of the functions required to fetch lists and manipulate cases. It also handles attachments for you by automatically creating the temp files on demand and preparing an input stream so that you can send the byte stream as the POST request body (with the multipart MIME type). Many areas are not covered, though, such as wiki or time tracking. It should be easy to extend the library to support those FogBugz features.