Positive Incline

Last week I received this:

#described_routes could make beautiful middleware

Why didn’t I think of that?

So I took a quick look at Rack, found there was almost nothing to learn, and over the weekend made the change. And it was well worth it: integrating described_routes into your Rails application is now much easier. There’s no need to modify your routes (the middleware recognizes and serves requests to /described_routes automatically) or your controllers (the discovery protocol’s link headers are added automatically to other requests). In fact the old integration method looks so ugly by comparison that I’ve deprecated it - it’s *that* embarrassing!

Now, run-time integration needs only this modification to your environment.rb’s Rails::Initializer.run block:

require 'described_routes/middleware/rails'
Rails::Initializer.run do |config|
  ...
  config.middleware.use DescribedRoutes::Middleware::Rails
  ...
end

Revised instructions (compare with the old):

1. Install the described_routes gem for the server
2. Add build-time integration to the server (a one-liner to add some useful Rake tasks)
3. Add run-time integration to the server (just the environment.rb modification above)
4. Install and run path-to (for an “instant” client API)
5. Profit!

Yes, it’s for Rack for Rails

The sharp-eyed reader will have noticed that despite the move to Rack, we’re still discussing a Rails integration. What about described_routes for other Rack-aware or Rack-based frameworks?

Most of the new middleware’s functionality exists in an abstract class DescribedRoutes::Middleware::Base but it needs two methods implemented for each framework:

1. get_resource_templates - get named routes from the application and convert to ResourceTemplates
2. get_resource_routing - map a request to a ResourceTemplate and its parameter list

In DescribedRoutes::Middleware::Rails:

1. get_resource_templates hooks into described_routes code originally based on ‘rake routes’, and
2. get_resource_routing extracts the controller name, action name and path parameters from a Rack environment member ‘action_controller.request.path_parameters’ populated by Rails as it processes the request - our stuff must happen afterwards.  The route name is reverse-mapped from the controller and action name.^[1]

It should be clear now that both methods are necessarily framework-specific; indeed Rack does not provide routing itself.

The test of described_routes’s underlying framework-neutrality will be its integration with a framework other than Ruby on Rails. This should be easier to achieve now than previously; perhaps someone with more knowledge and need than me will beat me to it (please be my guest!). I’m tempted meanwhile to double the challenge and attempt it in Python for WSGI-based frameworks (wish me luck!).

Tags: described_routes, link_header, path-to, python, rails, resource_template, rest, ruby

This entry was posted on Tuesday, August 4th, 2009 at 12:01 pm and is filed under Web Integration. 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.