REST Url for Lists

Question

Let's say I have a method that returns a list of customers and as input has a list of states and list of sizes, something like

return customers where state in (NY, CA, TX) and size in (Small, Medium)

What would the best RESTFul URL that I should use? The problem that it is a query and does not point to a specific 'resource'. Here are some options that I am mulling over.

1. somesite.com/customers?state=NY,CA,TX&size=small,medium (old style)
2. somesite.com/customers/state/NY,CA,TX/size/small,medium
3. somesite.com/customers/state=NY,CA,TX/size=small,medium
4. somesite.com/customers/state(NY,CA,TX)/size(small,medium)

Answer 1

I think #1 (somesite.com/customers?state=NY,CA,TX&size=small,medium) is the best of the bunch. The customers are the resources, and the query string is just placing restrictions on the resources being requested.

Answer 2

Option 1 - query params are intended for exactly that. Parameters for your query.

Edit: Expanded

You are interested in a list of customers therefore the last "folder" should be "/customers". The fact that you want a subset of these and that that subset is variant depending on input, and in combination leads you to query params acting as filters. (Nothing else would make sense as you see by being compelled to ask the question).

The real question you have is whether the params are going to be inclusive or exclusive by default (i.e. AND or OR). That question has already been asked here if I can just find it...

Answer 3

Personally, I'd use the 4th approach, but with the '+' sign instead of parenthesis:

somesite.com/customers/NY+CA+TX/small+medium

RESTful-style your Models are not necessarily all the RESTful Resources you should offer... You can add any number of (artificial) resources as you see fit, even ones that would require a JOINs from your Models.

Answer 4

For what it's worth, URI naming conventions has nothing to do with REST. In fact, if you define a way of constructing your application's URIs out-of-band as part of your API, you are violating a constraint of REST. See: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven