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.

Kight

REST has no opinion about what your URLs look like. However this document has a bunch of suggestions tools.ietf.org/html/draft-gregorio-uritemplate-04 – Valetudinary

check out this to understand some of the good practices for designing RESTful API's saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices – Violist

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...

Veronicaveronika

check also this s.o. topic: #306771 – Veronicaveronika

how would you format the Id's? comma separated? and what is the limit on how much data you can put on query string? would it be better (allowed?) to use post and post parameters instead? – Kight

I would avoid specifying the query parameter in a HTTP header because that would mean (a) that you could have multiple queries which are completely different but which share the same URI, and (b) it would remove the ability for intermediate proxies to cache query results to improve performance. – Hube

I would rather use the following URL's for your resources /users/dave/books/ – Violist

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.

Zumwalt

Answer 3

this is just my opinion:

GET /user/dave/library/book/IDList      //retrieves a list of books id's
or
GET /user/dave/library/bookID           //retrieves a list of books id's

GET /user/dave/library/book             //retrieves a list of books
GET /user/dave/library/book/1           //retrieves info on book id=1
GET /user/dave/library/book/1-3         //retrieves info on book id>=1 and id <=3
GET /user/dave/library/book/1/tags      //retrieves tags collection (book id=1)

Crake

Answer 4

You can use a paginator

Some restful API's work with a paginator for huge resources like:

http://example.org/api/books?page=2

The server delivers for example 100 records (in this case books) per page. And you can sort the books using a sortby in your get request. With the above request you would get books 101-200 (if so many in the database). The response can tell you something about the amount of books and amount of pages, what is the next page and the previous page but then you go more to HATEOAS.

Otherwise if you want to get certain id's i would do it like this:

http://example.org/books?id=[]2&id=[]5&id=[]7&id=[]21

A get request with an array of id's (id = [2,5,7,21]) which returns the books with those respective id's

Hatchet