CODEWITHSUNDEEP
apirestnaming
user1800734
user1800734

Reputation: 233

REST API naming convention

Given this URI:

/myapp/books/status/{status}

For example :

/myapp/books/status/new

This will return all books flagged with this status.

What would be a proper URI for return all books NOT flagged with a specific status?

/myapp/books/notstatus/new

I would like to return a collection of all books except the ones with a certain status..

Please advice...

Upvotes: 5

Views: 1952

Answers (2)

Regfor
Regfor

Reputation: 8101

As I know there are a couple of ways, and all of them are correct (from REST perspective):

  • Query string parameters

myapp/books?status=new

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

  • In URI, also good

myapp/books/status/{status}

Personally I prefer either Query string or OData.

OData is especially good when technology specific (ASP.NET Web API, WCF Data services, by non-Microsofts should also be equivalents) helps to avoid writing any code for such queries.

It allows to expose prefiltered collection and then filter it from client with such query. In such scenarios when exposing collections, I'm using OData queries.

Upvotes: 2

Ray
Ray

Reputation: 41508

I'd recommend using query parameters for filtering status for your books list resource:

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

Both queries return the same resource (a list of books), you're just filtering out the types you want in that list, so the use of a query param makes sense. I use the not_ prefixed to the status to do inverse queries, but you can use whatever convention you want.

REST doesn't require you to avoid get parameters (it seems some people think get parameters are voodoo), just don't use them to make faux-RPC calls :)

The reason I like this method is it opens up your options later when you might want to add a check for all books with multiple pieces of info such as ones that have a status of new and condition of good.

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

If you try to break that down into url segments instead of query params, it gets messy very quickly.

Upvotes: 5

Related Questions