21 June 2010

Which book API to use for a mobile book app? (Part I)

So I'm starting to look into creating a book management app that will run on my Android phone. There are a few of these apps available in the Android Marketplace, but none of them do quite what I'm looking for.

What am I looking for? Well, I have a few requirements:
  • Needs to be able to add new books easily (via barcode scanner)
  • Should automatically get book info from online sources
  • Should allow books to be arranged in "shelves" or tagged
  • Should store my list of books online
The first few requirements are fairly easy - it's the last one that makes things interesting. While it'd be far easier for me to create (yet another) local database to store this information, there are some big advantages to having everything stored "in the cloud":
  • The data is available on other devices (via the website)
  • The data is backed up (if something happens to my phone)
  • It's easy to share
  • ...
Given this requirement, I could either write my own online data storage app or I can take advantage of the already-existing services out there.

"Writing my own" is not as bad as it sounds. A simple AppEngine app could be thrown together to handle this. The problem is that while this would work for me with my books, it wouldn't be able to handle other people's books (without running into the free service limits). The code could be open-sourced to make it easy to others to create their own instance of this web app for their own books, but that's starting to become needlessly complicated.

So using an existing online book manager is the right path to take. Fortunately, there are a bunch of decent ones out there to choose from that seem to provide (at least part of) what is needed:The trick is to find which one (or more) supports the features that I want. Note that there are a few other services out there (like Shelfari) not listed because they don't have a developer API. If you know of any others that are worth investigating, please let me know.

Now, in an ideal world, this (proposed) phone app would be a simple front-end and the user would be able to select from a number of different online book managers to use as a backend. While this is great for users (they can pick/choose their favorite online book management site), the sad reality is that this sort of things is challenging for (mostly) technical reasons. This is where a standard interface for accessing personal libraries would come in handy. But, alas, such a thing does not exist.

So how can I choose from amongst the available options? It seems I need to sit down with each of them and see what they're capable of and then compare that with my requirements listed above.

To do that, I've broken things out into 4 sections and evaluated each API. These four sections are : Access, Read/Write, Auth and Restrictions.

Quite simply this evaluates whether or not the API provides access to the required data.

In its simplest form, a "user library" app needs a list of books (ISBNs or EANs) and way to arrange them into groups (bookshelves or labels).

More generally, my app needs access to an API that provides the ability to:
  • Get general book info
    • Given an ISBN, get the title, author, pub info, thumbnail, ...
  • Get user specific info
    • Get a list of bookshelves (or get a list of labels)
    • Get a list of books in a bookshelf (or get a list of all books with a particular label)

Technically, this is part of "Access", but I broke it out for some reason during the evaluation and ended up leaving it that way. Since all APIs (pretty much by definition) provide read access, the real question here is "do they provide write access?".

The write access required is:
  • Update user specific info
    • Add a new bookshelf (or label)
    • Add a new book
    • Add/update user info for a book
The bare minimum is to be able to add a new book to a shelf. The other 2 are 'would be nice's.

This is where things start getting tricky. "Auth" is a combination of "authentication" (is the user who they say they are) and "authorization" (does the user have access to the requested resource).

So the question is : "How does the API authenticate/authorize the user to provide access to the data?"

Often there will be different levels of Auth provided by the same API. To get general book info, the API doesn't need to know who you are. But to get (or update) info on a private shelf, it needs to verify that you are the owner of that shelf.

As a preview of things to come, this is the area where most APIs fall down. The most common problem being that they attempt to authorize the application (through the use of a devkey or something similar) rather than the user of the application.

This (almost) final section discusses limits and licensing restrictions on the API.

Most of the restrictions in the license agreements are pretty typical. Things like:
  • You can't use the API to harvest data
  • You can't relicense the data
  • You agree not the break the law
  • Not for commercial use
So I'll only be breaking out issues that either fall outside what is typical or that may impact the app.

The 2 common issues that pop up here are:
  • Acceptable use for the API - Does the agreement forbid what I'm trying to do?
  • QPS (queries/second) restrictions - Are the QPS restrictions low enough to cause concern?

And finally, each sections ends with a brief set of conclusions. It's important to note that these conclusions do not evaluate the service as-a-whole, but rather specifically to their suitability for this particular application.

Public disclosure: I should note that, while I do work at Google, I do not work on the Android or Google Books teams, so I'm not tied to promoting these particular products. My hope with this evaluation is to compare the various options in a fair manner since this Android book-app project falls outside the scope of what I do at work. In addition, I should explicitly state: "The views represented here are my own and not those of my employer."

So, onward with the API evaluations (in Part II)

[Edit: added link to Part II]

No comments: