Chris Cruft

The support that Rails has provided for developing RESTful applications is nothing short of amazing considering it was added on long after Rails had an established URL-mapping mechanism (Routes.draw).  But I want more.  Specifically, I want my resources to have a more complete life.

Warning: I am not an expert in Rails or REST, but sometimes I think there has to be a better way.

Background: in the current (late summer 2007) Edge Rails, RESTful resources (ActionController::Resources) are defined primarily for the purpose of creating named routes with a DSL (map.resource …).  A very important by-product of generating named routes is the helper methods available to generate routes in views and controllers.  The net result is a tidy means of generating and recognizing RESTful URIs.  A typical exploitation of these features looks like this:

1. Define Routes per Resource
2. Recognize Incoming Request’s Route
3. (process request in controller)
4. Generate view, typically with one or more links

Repeat steps 2 through 4 as required.

In step one, the Rails programmer does the hard work: modeling the resources, the interface to those resources, the mapping of resources to controllers, etc.  Rails honors our work and uses these abstract resources to recognize routes (in step two) and to help up generate routes (in step four).  But what about step three?  Can we exploit our abstract resource model here?  Let’s recast the typical methods in a controller that backs a resource:

def index
  identify resource
  manipulate resource
end

def destroy
  identify resource
  manipulate resource
end

def create
  identify resource
  manipulate resource
end

For the index action, the identified resource is a collection represented by a Class or an association.  For the destroy (and show and edit) actions, the identified resource is a member represented by an ActiveRecord model instance.  For the create (and new) actions, the resource is a new, unsaved, AR model instance.  Every controller action that handles a REST request starts with the identification of the resource.  For the following examples, let’s define some resources:

map.resources users do |user|
  user.resources groups, :controller => ‘groups’ do |group|
    group.resources tags, :controller => ‘tags’
  end
end

map.resources groups do |group|
  group.resources users, :controller => ‘users’ do |user|
    user.resources tags, :controller => ‘tags’
  end
end

map.resources vehicles do |vehicle|
  vehicle.resources wheels, :controller => ‘wheels’
end

map.resources unicycles do |unicycle|
  vehicle.resource wheel, :controller => ‘wheels’
end

As these resource definitions show, sometimes resource identification is trivial and sometimes it’s not…

1. /vehicles/567/wheels
2. /unicycle/234/wheel
3. /users/17/groups/2/tags
4. /groups/2/users/17/tags

In example #1, wheels is a has_many association of a vehicle instance.  It would be nice if Rails helped us find the vehicle instance and pointed us towards its has_many association.  What we get is the params hash, which indicates the vehicle instance, and the invocation of WheelsController.index, which implies the wheels collection association.  Indirect, but adequate.

In example #2, wheel is a has_one association of a unicycle instance.  Rails should help us find the vehicle instance and point us towards the association.  Much as in the first example, Rails gives us a params hash and invokes the WheelsController.show method.  Again, indirect but adequate. 

Examples one and two together illustrate the first ugly problem with resource identification:

Problem One: The arity of resources is implied by the invoked controller method instead of being explicit.

In example #3, tags is a has_many association of a Group instance.  In example #4, tags is a has_many association of a User instance.  The params hash and invoked method  are identical for these two requests.  Rails really lets us down here: short of parsing the request path, there is nothing to distinguish these two requests.

Problem Two: The hierarchy of the request’s resource chain is not preserved.

I believe these two problems stem from the outdated perception of the URL only as a means of triggering a specific controller action and providing some unordered key-value parameters.  In the RESTful world, however, the URL has become a resource specifier.  And that means hierarchy matters and parameters are not limited to key-value pairs.  In a nutshell, Rails needs to help us match a concrete request with our abstract resource model.  Until it does, identification of RESTful resources will continue to be a pain in the ass.

In the meantime, I have taken two steps to help the programmer match an abstract resource to the concrete request by providing some extra information to the controller.  First, I have made the matched route available to the controller as an attribute of the request by monkey patching ActionController::Routing::RouteSet and ActionController::AbstractRequest.  Now I can see the specific components of the request in an abstract way instead of as a string.

But once I had made that change, I realized I was getting very close to the holy grail of the actual abstract resource definition (from routes.rb) used to generate the route.  It was only a couple of more monkey patches before I had the source ActionController::Resources::Resource instance available to the controller as well.

Now in my controllers I can see which of my abstract resources (as defined in routes.rb) matches the incoming request.  That goes a long way towards getting the matching AR model instances instantiated. 

My only remaining beef is that the abstract route definitions (in routes.rb) do not store any meaningful hierarchy information.  In my example above, the subordinate collection resource beneath a group and called ‘users’ is only aware of its parent resource (a group) though a couple of strings (name_prefix and one other).  That means that even when I know the abstract resource that matches the incoming request, I can’t really see its enclosing resources with inferring them from string pattern matching.  Rails should store the parent resource for any nested resources.  That will be my next monkey patch.

Resources
    Jamis Buck’s awesome tutorial on Rails Routing
    Discussion of some of these issues from a different angle
    Group trying to improve REST resource identification

Technorati Tags: Rails REST routing

This entry was posted on Friday, August 3rd, 2007 at 13:06 and is filed under Software Development, Rails. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.