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
require 'described_routes/middleware/rails' Rails::Initializer.run do |config| ... config.middleware.use DescribedRoutes::Middleware::Rails ... end
Revised instructions (compare with the old):
- Install the
described_routesgem for the server
- Add build-time integration to the server (a one-liner to add some useful Rake tasks)
- Add run-time integration to the server (just the
- Install and run
path-to(for an “instant” client API)
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:
get_resource_templates– get named routes from the application and convert to ResourceTemplates
get_resource_routing– map a request to a ResourceTemplate and its parameter list
described_routescode originally based on ‘rake routes’, and
get_resource_routingextracts 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.
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!).
Actually it’s a shame that Rails doesn’t make the request’s route name or route object available anywhere – is there anyone else who would use it?