Status of Rails.application.routes.recognize_path()

rubyonrails-core
1

Sorry if this question isn’t really “Ruby on Rails: Core” material. I feel it is, at least kind-of (also, I first tried asking in “Ruby on Rails: Talk” to no avail.).

So, while writing a gem (engine) for rails, I found that I needed to have my app (in a pre-filter) directly query the router. In the “old” days, this was done using ActionController::Routing::Routes.recognize_path() . My 2nd edition of “Agile Web Development with Rails” (which covers rails 1.2) even demonstrates how to use it in a rails console to verify your routes. This is now deprecated (in rails 3.0.x) as indicated by the following warning in my application log:

DEPRECATION WARNING: ActionController::Routing::Routes is deprecated. Instead, use Rails.application.routes.

So, today you use Rails.application.routes.recognize_path(). Beautiful. It works great.

However, when trying to re-learn or re-discover this method (I hadn’t used it in quite a while) I noticed it isn’t documented (http://api.rubyonrails.org/). Rails.application.routes returns an instance of the ActionDispatch::Routing::RouteSet class which, looking at the source, has the “#:nodoc:” rdoc tag to prevent it being included in the project documentation.

This communicates to me that this isn’t considered part of the public API and is therefor subject to change, be renamed, whatever.

So my question is, is this true? Since I’m writing a gem, a rails engine that needs to call this method, am I in danger of a future rails point release breaking my gem? Or, is the lack of documentation superfluous and I can be assured that this method: Rails.application.routes.recognize_path(path, environment = {}) will always be available (with that signature and behavior)?

The fact that the older, deprecated way of accessing this method directs you to this new method in the deprecation warning, however, communicates that this is still a kind of public (perhaps just “less” public?) method. Is this true?

Thanks in advance for any input. I would just like to know since I’d like to avoid relying on internal methods that could change in a point-release.

2

I think this will change in the future, but you should be safe to rely on it for 3.0.x and 3.1.x.

3

Just for the record, the RouteSet class was not marked as :nodoc: as part of Rails 3 - it has been :nodoc: for years. What's been deprecated is accessing the routes by using the constant ActionController::Routing::Routes which was aliased to ActionController::Routing::RouteSet.

Andrew White

4

Thanks in advance for any input. I would just like to know since I’d like to avoid relying on internal methods that could change in a point-release.

Just for the record, the RouteSet class was not marked as :nodoc: as part of Rails 3 - it has been :nodoc: for years. What’s been deprecated is accessing the routes by using the constant ActionController::Routing::Routes which was aliased to ActionController::Routing::RouteSet.

Ah yes, my observation of the :nodoc: marker was, for sure, just on the current version. I didn’t mean to imply it had ever been otherwise. It was, in fact, the book “Agile Web Development with Rails” (2nd Edition) which credits Dave Thomas and, more importantly (to a lay reader) David Heinemeier Hansson, lending it an “official” quality, that I cited as my original source of knowledge of the method.

Just for kicks, I just checked the 3rd edition. It also still has, “Use the recognize_path method to see how routing would parse a particular incoming path…” (p 428). The third edition adds Sam Ruby as an author, in addition to Dave Thomas and DHH. However, the currnet (4th) edition has no mention of it anywhere.

Well, I’m sure you’re all very interested in this trivia :).