Goodreads Developers discussion

122 views
API wishlist

Comments Showing 1-30 of 30 (30 new)    post a comment »
dateDown arrow    newest »

message 1: by Casper (last edited Aug 23, 2010 12:16AM) (new)

Casper Gasper (caspergasper) | 32 comments Hi there,

Based on user feedback there are some extra features I'd really like to see in the API --

- Ability to remove a book from a shelf.
- Ability to add a book to multiple shelves at once.
- A size param for /updates/friends.xml to only download the Nth most recent updates.
- A way to get your current status (I think I can do this with the rss feed, but again would like a size param to only get the most recent).
- Get multiple bookshelves
- Searching for quotes (I can get your most recent, again from an rss feed)

Think that's about it. If you could fix any of these that would be great.

thanks,

Casper.


message 2: by Michael (new)

Michael Economy (michaeleconomy) Ability to remove a book from a shelf.
-you should be able to do this already... Clearly the docs are lacking. I'm gonna ask around.

Ability to add a book to multiple shelves at once
- i think you might be able to do this also, i'll try and track that down also

A size param for /updates/friends.xml to only download the Nth most recent updates.
-we've got a ticket open for this, I escalated it recently.


A way to get your current status (I think I can do this with the rss feed, but again would like a size param to only get the most recent).
- I'll make a ticket to add this.


Get multiple bookshelves
-This call would be too slow for us to reliably do. You can select the "all" shelf if you want.

Searching for quotes
- I'll add a ticket for this one also.


message 3: by Louise (last edited Aug 24, 2010 07:52PM) (new)

Louise | 36 comments Added a param for /updates/friends.xml to show only the Nth most recent updates:

max_updates=N


message 4: by Adam (new)

Adam (jademason) | 66 comments To Casper's wishlist I would add methods to interact with groups:
- Search Groups
- Get Groups
- Get User's Groups
- Join Group
- Leave Group
- Get Group Members
- Get Group Events
- Get Group Shelf / Shelves
- Get Group Events
- Respond to Event
- Get Boards for Group
- Get Topics for Board
- Get Messages for Topic
- Post New Topic to Board
- Post Reply to Topic
- Post Reply to Message


message 5: by Casper (new)

Casper Gasper (caspergasper) | 32 comments Goodreads staff, I'm sorry to complain but can you please try and avoid breaking the API? Over the last week changes have been made to /updates/friends.xml and review/list that were fairly minor but have basically made my app unusable. Don't worry about them now, it's easy enough to amend my code but I would like to see this doesn't happen again.

I know we all know this, but let me re-iterate -- a public API is a contract of expected behaviour, and if you want to encourage 3rd party developers you should honour it. When you need to update stuff (like when I or others request changes), please try to:

a) do it in a way that doesn't change current output (like an optional GET param), or even a new XML file.

b) if you really are going to change something, ensure it's not being used, or that you've given plenty of advance notice.

It would be nice btw to have slightly more unique names for the nodes -- there seem to be a lot that are identical, something like "image_url" could be replaced with "author_image_url" and "actor_image_url" for instance, and we can't all use XPath to pick them through the XML hierarchy (please don't go away and change them now though).

Sorry to rant, but I'm doing a great job of introducing enough bugs on my own, I really don't need the help :-)

Casper.


message 6: by Michael (new)

Michael Economy (michaeleconomy) Adam wrote: "To Casper's wishlist I would add methods to interact with groups:
- Search Groups
- Get Groups
- Get User's Groups
- Join Group
- Leave Group
- Get Group Members
- Get Group Events
- Get Group Shel..."



I'll ticket these.


message 7: by Michael (new)

Michael Economy (michaeleconomy) Casper wrote: "Goodreads staff, I'm sorry to complain but can you please try and avoid breaking the API? Over the last week changes have been made to /updates/friends.xml and review/list that were fairly minor b..."


I'm looking at review/list and it seemed like we added some data, but didn't change any existing elements. This should be expected on all of our api calls.


Because of the way our code is layed out, freezing api verisons is not particularly easy, but its something we're definitly considering.


We'll try and be better at announcing api changes, maybe we could start a newsletter.

We've been a consumer of the facebook api for over 2 years and its a huge deal keeping up with all their changes. They've got a much bigger team and still continually break compatability. Not that their the bar, but it's reallly hard!

Once we get the API the way we want it, it should stop changing so much. I envy flickr in that regard. They only add a new feature every couple years, but their api is so rock solid.


message 8: by Curtis (new)

Curtis Schofield (robot) | 39 comments I would like to depricated the XML API going forward and only implement json - it is small fast easy to parse , works in any language and has no ordering - can be easily nested - thus removing the Need for special names - not to mention it will allow us to test our API eaaier, won't require resorting to extra view code, and generally will move us towards a standard rest based API that anyone can consume.


message 9: by Adam (new)

Adam (jademason) | 66 comments Curtis wrote: "I would like to depricated the XML API going forward and only implement json - it is small fast easy to parse , works in any language and has no ordering - can be easily nested - thus removing the ..."

Why not support both? Many sites offer their API in either format, which makes them accessible to an even broader range of developers.


message 10: by Curtis (last edited Aug 27, 2010 01:57PM) (new)

Curtis Schofield (robot) | 39 comments Adam,

there are lots of reasons for not supporting both.

In my experience supporting more formats doesn't
create accessibility - supporting a more universal
format does.

XML is a dead horse that was turned into a golden hammer by the java community - the fact that android 1.6 uses a sax parser is a great example why a lite api format like json is appropriate - it will never require complex libraries to parse - nor to access - that is real accessibility.

catering to a standard that is computationally, over-expressed, and otherwise ungainly is more about not challenging peoples comfort and less about accessability.

This is not the opinion of goodreads.


message 11: by Curtis (new)

Curtis Schofield (robot) | 39 comments well..

here is a good reason to support xml aside json
http://ubikapps.net/?p=268

android doesn't have a proper json parser either.

(so wierd)


message 12: by Casper (new)

Casper Gasper (caspergasper) | 32 comments You missed the follow-up post here where the author was able to get superior performance with json on Android:
http://ubikapps.net/?p=419

I'd rather have a stable API using one method that 2 half-supported implementations.

I've already told Curtis privately what I think of his, er, views on XML :-) Nevertheless, for mobile devices there may well be benefits to shift to json, I'm prepared to bet some developers will be very unhappy with that choice though.

Casper.


message 13: by Curtis (new)

Curtis Schofield (robot) | 39 comments Well thank you Casper - I'm going to have to try that out :),

It is much more straightforward for me to develop and test one API and one format - in my experience that's the best way to go - after it is stable we'll worry about a group XML format API.

I'm certain about one thing - I can please some people sometimes, but I can't please all people all the time.

Hopefully we'll be able to give some great service and assistance - i have no experience with android dev or jackson - but I used to be a c and java coder and have some iPad experience so that may help.


This Is Not The Michael You're Looking For I'm pretty sure the standard programmer way is to please none of the people none of the time.


message 15: by Curtis (new)

Curtis Schofield (robot) | 39 comments @this-is-not-the-michael-you-re-looking-for

that is an interesting comment to make - I hear that you are pretty sure that the standard programmer's way is to please none of the people none of the time.

I'm sorry to hear that - I expect we'll be unable to change your mind if that is how you see things.


This Is Not The Michael You're Looking For Curtis, part of what I do for a living is write software. That wasn't meant as a dig at GoodReads, but rather a tongue-in-cheek comment about programming in general. I once deliberately put a "user out of luck" error into one of my programs just to see if anyone could would try something bone-headedly stupid enough to generate it (no one ever did).


message 17: by Curtis (new)

Curtis Schofield (robot) | 39 comments i hear that you are a professional developer and that you are making a generalization for the sake of humor. - Gatcha -

i code for fun and i find that at least i'm pleasuring myself - and if i could - it would be for others too.


message 18: by Adam (new)

Adam (jademason) | 66 comments MICHAEL wrote: "Ability to remove a book from a shelf.
-you should be able to do this already... Clearly the docs are lacking. I'm gonna ask around.

Ability to add a book to multiple shelves at once
- i think y..."


Michael - did you find an answer to how to add a book to multiple shelves, or remove it from a shelf?

Currently I do this by making multiple calls to the add_to_shelf method, once for each selected shelf. On the review.update call I tried specifying a list of shelves, delimited by pipes, but this did not have the desired effect.


message 19: by Rob (new)

Rob (rpboland) | 9 comments I would also be interested in hearing how to remove books from a shelf. +1

Also, I think it would be great if there was a more basic mapping of isbn->book_id. At the moment, I use the 'book.show_by_isbn' method, but this returns the entire goodreads book data. I only use the id tag at the very top and ignore the rest, which doesn't seem like the most efficient data transfer!


message 20: by Michael (new)

Michael Economy (michaeleconomy) Rob wrote: "I would also be interested in hearing how to remove books from a shelf. +1

Also, I think it would be great if there was a more basic mapping of isbn->book_id. At the moment, I use the 'book.show_b..."


I think i got side tracked on the remove from shelves thing, I'm writing this down this time....



It's basically the same amount of work on our end to pull of that data, would you guys want something with a smaller response? Would be trivial to add.


message 21: by Rob (new)

Rob (rpboland) | 9 comments Can't speak for the rest of the community, but I would definitely make use of a shorter response if it was available.

Apart from the data transfer considerations, part of my problem is actually the xml parsing issues. I have to deal with these before my code can interpret the XML, and I don't actually even need that information.

It's not a huge deal, it's just that a more simple data set (without the user reviews) would save my program this extra processing.


message 22: by Adam (new)

Adam (jademason) | 66 comments Data size hasn't caused me any technical or performance issues, but I am sure that my users who pay by the byte for their data would appreciate the opportunity to save a few cents.


message 23: by Michael (new)

Michael Economy (michaeleconomy) Ok, i'll open a ticket for a new slimmer isbn_to_id method.


message 24: by Louise (last edited Sep 14, 2010 04:51PM) (new)

Louise | 36 comments Rob wrote: "I would also be interested in hearing how to remove books from a shelf. +1

Also, I think it would be great if there was a more basic mapping of isbn->book_id. At the moment, I use the 'book.show_b..."


Sorry for the slow response, but removing a book from shelf works the same way as adding a book, except with an extra parameter (a=remove):

add_to_shelf.xml?key=YOURKEY&book_id=BOOKID&name=SHELFNAME&a=remove


Our docs are lacking in this area, so I'll update them to include removing.


message 25: by Adam (new)

Adam (jademason) | 66 comments Thanks Louise!


message 26: by Louise (new)

Louise | 36 comments As for adding to multiple shelves in one call, we currently don't support that. For now, developers will have to make one call per shelf they'd like to add to. How important is the multiple shelves feature for everyone?


message 27: by Adam (new)

Adam (jademason) | 66 comments When just adding a book to a shelf it isn't a big deal, but when submitting a new or updated review it would be nice.


message 28: by P_Racemosa (new)

P_Racemosa (Tzu-Jan) | 1 comments I would really like to see a way to search other users by different types of compatibility with what I have already posted. Like for example.
Most like your collection.
Most like your ratings
Most like your to reads and so on.
It would be a neat way to find new books (and friends) as you know they like stuff you do in one way or another.
I am a newbie at code so I am pretty sure this is out of my hands.


message 29: by Michael (new)

Michael Economy (michaeleconomy) P_Racemosa wrote: "I would really like to see a way to search other users by different types of compatibility with what I have already posted. Like for example.
Most like your collection.
Most like your ratings
Mos..."


We don't have those features yet, but we may in the future. Exposing existing features with the api is a much simpler processs.


message 30: by Curtis (last edited Sep 16, 2010 10:36AM) (new)

Curtis Schofield (robot) | 39 comments P_Racemosa wrote: "I would really like to see a way to search other users by different types of compatibility with what I have already posted. Like for example.
Most like your collection.
Most like your ratings
Mos..."



I think that is a great idea - fuzzy classifiers is one technique that can bu used to find people with compatibility to you.


back to top