Want a great API? Don’t use Goodreads’

I’m in the middle of a client project for a local public library – building a simple mobile site that makes book recommendations based on genres. The titles come from their RSS feeds and we grab additional data from Goodreads. Easy and fun right?

No. Wrong. Very Wrong.

To put it plainly, the Goodreads API is a mess. A convoluted, poorly designed, agonizingly slow mess. To demonstrate, I thought I’d walk you through a few of their API terms (found here).

1. Not request any method more than once a second. Goodreads tracks all requests made by developers.

This sucks. If in your app you want to query a book, grab a review, show the author’s bio, and recommend other books in that series, you need to make 4 API calls. To abide by Goodreads’ terms, you need to make that request last 4 seconds. Seriously?! It’s 2011 – I can make thousands of requests in that time from hundreds of other APIs. But the best part? It actually takes longer than 4 seconds because the response time from Goodreads per request is over 1 second. Plus, if you read term #5, they say you can’t store anything – so every pageload is going to take several seconds. Sounds like an awesome user experience, right?

3. Link back to the page on Goodreads where the data data [sic] appears. For instance, if displaying a review, the name of the reviewer and a “more…” link at the end of the review must link back to the review detail page. You may not nofollow this link.

I had no idea a webservice could be so selfishly greedy. What this is really saying is “We will NOT give you the full review of anything, you must link back to our site to see it, and you must give us link credit for every review you display in your app.”

This is all very frustrating. Goodreads has fantastic data – I’ll be the first to admit that – but they’re actively DISCOURAGING developers from using it!

But the worst part is the developer support.

I was building the application and came across the fact that only a handful of API endpoints returned JSON – the others only returned XML. Not a huge deal, but when trying to save as much time as possible due to aforementioned request time, I wanted to parse JSON in PHP rather than load the SimpleXML resources. I thought this was odd (maybe a bug) so I searched in the developer forums; lo and behold, someone else had the same request. They explained that they were using the Goodreads API as an example in a classroom setting and wanted to give the students JSON to work with. Here’s the response from a Goodreads employee:

“It’s a bit of work to add this. Someday it will likely happen, but probably not that soon. If you were using an API for a class, I don’t think our documentation is that great either. I think flickr has a much more mature api.”

Yes. A Goodreads employee said “That’s too hard so we won’t do it, and our API and documentation isn’t good enough for you to use in a class. Use something else.”

(You can read this entire thread here: http://www.goodreads.com/topic/show/453508-can-we-get-json-for-all-calls?page=1#comment_27316799)

In the end, I’m saddened and appalled. I can’t deliver the product a client wants, I’ve spent several hours fighting an API that is simply poorly documented, developed, and supported, and as someone working on building an API for another product I’m utterly shocked that something like this can be called an active release from a company that has raised nearly $3 Million in venture funding.

It’s 2011 guys. Catch up.