Rails: How to parameterize access to a RESTful resource?

Question

I'm looking for a restful way of passing through options to a service. Right now I have a devices resource accessed in standard rails manner with:

map.resources :devices, :member => [:historical]

So I can get my device with /devices/:id and I can get historical data with /devices/:id/historical

I'd like to actually add a param onto the historical URL that specifies a range, so when I query for historical data, i can get it back by hourly, daily, weekly, monthly. Something like /devices/:id/historical/:range

Is there a way to modify my route setting above to accommodate this? Or do I just have to pass it in like /devices/:id/historical?range=hourly

I'd prefer the former, but I'm not sure if that's breaking Restful conventions or what the best way to go about this is.

Answer 1

Having range as a path segment, or a query parameter are both potentially RESTful.

The question is really a design issue. Do you want to model the historical data as a single resource with a parameter, or do you want to model multiple resources? This is the same kind of decision that we make when doing OO design. Do you want one class with type property or a bunch of subclasses? Or database design, do we store the data in multiple tables or one table with a discriminator column?

As long as you use the HTTP verbs correctly to manipulate that resource then you will not violate the relevant REST constraints.

Answer 2

I think that really your question comes down to how to know when it's appropriate to represent something as a resource and when to parameterize it using a query string.

I don't know your domain, but from your question it appears that historical data about a device is a resource and that accessing subsets of that data through a range is best represented as a query string, in the same way that you might paginate a large list of items.

Something else to consider is caching, because if you want to page cache each range individually then you will have to use path segments within the route i.e. :range. That way Rails will generate a unique HTML file on disk to represent that range. If you use a query string then it will effectively get ignored and the same HTML file will be returned for different ranges.