RESTful URI for Filtering Nested Collections

Question

I'm looking for a good way to form a URI for a resource that filters on a collection of values contained within records. For example, say you have a recipe database and you want to search for recipes that contain "cherry" (obviously most recipes would contain multiple ingredients). If I just want to filter on single values, I could do something similar to the following: ``` /recipe/search/?name=Spaghetti ``` But what about filtering on multiple values? I was considering something like the following: ``` /recipe/search/?ingredients=contains=cherry ``` Any thoughts on this? Is there a "standard" for a filter of this kind? Update: One problem I have with my idea is the way it gets handled on the backend (in my case Rails). When querying the server with this particular format, Rails generates a Ruby hash that could get ugly like the following: ``` {"ingredients"=>"contains=cherry", "action"=>"search", "controller"=>"recipe"} ```

Accepted Answer

Your URI

First of all, in contrast to other answers I'll start from a `REST` perspective and then find appropriate additions to it. I am not strong in Ruby so bear with no-code on the backend.

- Recipies are the entities you wanna present your users find them at `/recipies`

- HTTP has QUERYS for filtering wanna have sorted those recipies by date? use `/recipies/?sortby=date&sort=asc`

- Only recipies with cherries goes similarly: `/recipies/?ingredients=cherry`

So that's the REST way of structuring your basic URL. For multiple matches there is no official way to do it, but i'd follow user1758003. This is an intuitive construction of the url and easily to parse on the backend, so we have `/recipies/?ingredients=cherry,chocolate`

Don't forget `/recipies/search` is not restful because it mirrors `recipies` and does not represent an independent entity. However it is a great place to host a searchform for visitors to your site.

Now there are some additional questions packed into the first, let me address them one by one:

I have a website consuming this api, how should the search form look like?

Give your visitors a `/recipie/search` page or a quick filtering possibility on `/recipies`. Just set the `<form action="/recipies" type="GET">`. The browser will add all parameters as an Query string after `/recipies`.

Advanced functionality

A request to `/recipies` should list all. If you add a query every parameter of the query must be respected. so `/recipies/?ingredients=cheese` MUST only return cheesy recipies. For multiply query parameter values there is no fixed standard but I'd like a service to be intuitive. I read `GET /recipies/?ingredients=cherry,chocolate` as `Get me the recipies which have ingredients of cherry and chocolate`. To get a list of recipies containing either cherry or chocolate I'd want to write the URI like `/recipies/?ingredients=cherry|chocolate` which makes it visually very different from a comma and has a predefined meaning (OR) in programming contexts.

RESTful URI for Filtering Nested Collections

Solution

Problem