REST API call : filter a resource on attributes

[navyad]

I'm building a REST API, i have a resource say Movies.

1) POST : movies/

2). GET : movies/{movie_id}

call 1) creates a post

call 2) when movie_id supplied, it returns specific movie's details, otherwise returns all movies.

Now i have to filter out the movies based on movie attributes like popular, rating etc

My doubts is :

Should there be separate URL for filtering the movies like 

GET: movies/filter/

This call will have GET parameters like popuplar, rating etc And based on those parameters movies can be filtered out.

Not sure what is the standard way to handle this case, please share your thoughts on this,

[Ben Schaaf]

I did find Vimeo's API, https://developer.vimeo.com/api/spec#filtering has a filter attribute- which may be something you can ponder.

But, to me, it sounds like you are really submitting a search query, if that's the case then you are on the right track:

GET movies/search?rating=PG_13&genre=comedy

There is a plethora of search api docs you can glean information from.  

But, popular, and similar attributes (like genre, for example) to me could be different endpoints, like:

GET movies/lists/:list_id (where list_id in this case is "popular"), or

GET movies/genres/:genre_id

I am parsing out like-functionality, attempting to make it clear. Successful APIs are obvious and transparent, hiding everything behind one filter endpoint may not be the best long-term solution.

Apologies if I am not interpreting your question correctly, just adding my input.

Good luck!

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Ralf Handl]

You might want to look at OData's $filter system query option, see http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc405997946.

This would allow you to

GET movies?$filter=popular and rating gt 4

assuming "popular" is Boolean and "rating" is numeric.

[Justin Halsall]

I personally like the way Rails, Node, Django and other frameworks handle hashes in query strings and utilise those for filtering

eg. movies?filter[popular]=true&filter[rating][gt]=4

On the server side you will receive something like this (JSON):

filter: {

  popular: true,

  filter: {

    rating: {

      gt: 4

[wiki1000]

If the client is able to store a "movie_id", it shall be able to store the whole URI. This is why using an URI template to specify the location of an opaque id inside a URI which shall itself be opaque does not make sense.

However, it makes sense to express a query in a GET in providing understandable values, the URI template being:

/movies{?name}
/movies{?genre,min_rating} with an AND semantics

for more complex queries, why not providing a link such as:
Link: <>;rel=movie_query;accept-post=application/sql; type=text/uri-list