REST API question on how to handle collections as effective as possible while still conforming to the REST principles

Question

Im pretty new to REST but as far as i have gathered i understand that the following URL's conform to the REST principles. Where the resources are laid out as follows:

/user/<username>/library/book/<id>/tags
          ^         ^           ^   ^
          |---------|-----------|---|- user resource with username as a variable
                    |-----------|---|- many to one collection (books)
                                |---|- book id 
                                    |- many to one collection (tags)


GET /user/dave/library/book             //retrieves a list of books id's
GET /user/dave/library/book/1           //retrieves info on book id=1
GET /user/dave/library/book/1/tags      //retrieves tags collection (book id=1)

However, how would one go about optimizing this example API? Say for example i have 10K books in my library and i want to fetch the details of every book in my library. should i really force a http call to /library/book/<id> for every id given in /library/book? Or should i enable multiple id's as parameters? /library/book/<id1>,<id2>... and do like bulk fetching with a 100 id's at a time?

What does the REST principles say about this kind of situation? and what are your opinion(s)?

Thanks again.

Answer 1

This is strictly a design matter.

I could define a bookc resource and use it like this:

GET /user/dave/library/book?bookList=...

how do you further specify the bookList argument is really a matter of what kind of usage you envisage of this resource. You could have, e.g.:

GET /user/dave/library/book?bookList=1-10
GET /user/dave/library/book?bookList=1,2,5,20-25

or you could simply page through all of the books:

GET /user/dave/library/book?page=7&pagesize=50

But in my mind, especially the form with a long list of "random" ids seems pretty unfit. Maybe I would instead define a filter parameter so I can specify:

GET /user/dave/library/book?filter=key,value&filter=key,value

As to your question about HTTP URL length limit, the standard does not set any. But browser may vary... look at this S.O. topic

To be more strictly RESTful, the query parameter could be specified through HTTP headers, but the general idea I wanted to convey does not change.

Hope this seems suitable to you...

Answer 2

Above looks good, but I would change to plural names, it reads better:

/users/{username}/books/{bookId}

What I don't understand is the use-case of passing comma-separated list of ids. The question is how you get to the ids? I guess behind the list of ids there are semantics, i.e. they represent a result of a filter. So instead of passing ids I would go for a search api. Simplistic example:

/users/dave/books?puchasedAfter=2011-01-01
 

If you want to iterate through your 10K collection of books, use paging parameters.