REST API naming convention

Question

Given this URI:

/myapp/books/status/{status} 

For instance:

 /myapp/books/status/new 

This will return all books marked with this status.

What would be the correct URI to return all books not marked with a specific status?

 /myapp/books/notstatus/new 

I would like to return a collection of all books, except those that have a certain status.

I ask for advice ...

Answer 1

I would recommend using query parameters for filtering status for your book list resource:

 myapp/books/?status=new myapp/books/?status=not_new 

Both queries return the same resource (list of books), you just filter the types you want in this list, so using a query parameter makes sense. I am using not_ with a state prefix to execute callbacks, but you can use whatever convention you want.

REST does not require you to not receive parameters (it seems some people think that getting parameters is voodoo), just do not use them to make faux-RPC calls :)

The reason I like this method is to open your options later, when you want to add a check for all books with several pieces of information, such as those that have new status and good condition.

  myapp/books/?status=new&condition=good 

If you try to break this down into URL segments rather than request parameters, it will be very messy.

Answer 2

As I know, there are several ways, and all of them are correct (in terms of REST):

• Query String Parameters

Myapp / books? Condition = New

• OData Queries http://www.odata.org/documentation/uri-conventions

myapp / books? $ filter = status eq 'new'

• The URI is also good

Myapp / books / status / {status}

Personally, I prefer either the query string or OData.

OData is especially good when specific technologies (ASP.NET Web API, WCF data services, non-Microsoft should also be equivalents) helps to avoid writing code for such requests.

It allows you to expose a pre-filtered collection, and then filter it from the client with such a request. In such scenarios, when exposing collections, I use OData queries.