Rest uri design concrete example

Question

A question about REST uri design. In the official web api tutorial i have seen the following uri:

Get a list of books by publication date:    /api/books/date/2013-02-16

Following the rest principles it's not better using the following uri?

/api/books?date=2013-02-16

Thanks

Answer 1

There are no hard rules about were parameters should go in this case. Some place them in the URL path some add them to the query string. Do note that in REST there is no emphasis placed on the way URLs should look like. People create them hierarchically because it makes sense to do so given their domain e.g.:

/api/books/         # all books
/api/books/100      # details about the book with id=100
/api/books/mystery  # all books in the mystery category

On the other hand, /api/books/date/2013-02-16 is a little bit of a stretch, again because people reason about hierarchies of resources and most of the times model their APIs as such, so given that they would expect /api/books/date to also return some books in a larger category than /api/books/date/2013-02-16 does. But in this case it doesn't really make sense, so maybe that's why you find /api/books?date=2013-02-16 to be a more natural choice.

I would also prefer /api/books?date=2013-02-16 in this case. But again, there are no hard rules on what the better choice is, see for example this: REST API Best practices: Where to put parameters?

Answer 2

They are equal. According to the URI standard, the path contains the hierarchical part of the identifier while the query part contains the non-hierarchical part. Now in the case of map reducing a collection you can consider the filter both hierarchical and non-hierarchical depending on your taste.

Btw. I prefer the param:value solution in the path and ending the URIs of the collections (or reduced collections) with slash, so: /api/books/date:2013-02-16/, but afaik. that is just best practice, not standard... :-)

According to the uniform interface constraint of REST, you have to apply existing standards over custom solutions, that's why we follow the URI standard in this case...