Guides.rubyonrails.org

Chapters

1. The Dual Purpose of Routing
   • Connecting URLs to Code
   • Generating URLs from Code
2. Quick Tour of routes.rb
   • Processing the File
   • RESTful Routes
   • Named Routes
   • Nested Routes
   • Regular Routes
   • Default Routes
3. RESTful Routing: the Rails Default
   • What is REST?
   • CRUD, Verbs, and Actions
   • URLs and Paths
   • Defining Multiple Resources at the Same Time
   • Singular Resources
   • Customizing Resources
   • Controller Namespaces and Routing
   • Nested Resources
   • Route Generation from Arrays
   • Namespaced Resources
   • Adding More RESTful Actions
4. Regular Routes
   • Bound Parameters
   • Wildcard Components
   • Static Text
   • Querystring Parameters
   • Defining Defaults
   • Named Routes
   • Route Requirements
   • Route Conditions
   • Route Globbing
   • Route Options
5. Formats and respond_to
   • Specifying the Format with an HTTP Header
   • Recognized MIME types
6. The Default Routes
7. The Empty Route
   • Using map.root
   • Connecting the Empty String
8. Inspecting and Testing Routes
   • Seeing Existing Routes with rake
   • Testing Routes
9. Changelog

1 The Dual Purpose of Routing

Rails routing is a two-way piece of machinery – rather as if you could turn trees into paper, and then turn paper back into trees. Specifically, it both connects incoming HTTP requests to the code in your application’s controllers, and helps you generate URLs without having to hard-code them as strings.

1.1 Connecting URLs to Code

When your Rails application receives an incoming HTTP request, say

GET /patients/17

the routing engine within Rails is the piece of code that dispatches the request to the appropriate spot in your application. In this case, the application would most likely end up running the show action within the patients controller, displaying the details of the patient whose ID is 17.

1.2 Generating URLs from Code

Routing also works in reverse. If your application contains this code:

Then the routing engine is the piece that translates that to a link to a URL such as http://example.com/patients/17. By using routing in this way, you can reduce the brittleness of your application as compared to one with hard-coded URLs, and make your code easier to read and understand.

2 Quick Tour of routes.rb

There are two components to routing in Rails: the routing engine itself, which is supplied as part of Rails, and the file config/routes.rb, which contains the actual routes that will be used by your application. Learning exactly what you can put in routes.rb is the main topic of this guide, but before we dig in let’s get a quick overview.

2.1 Processing the File

In format, routes.rb is nothing more than one big block sent to ActionController::Routing::Routes.draw. Within this block, you can have comments, but it’s likely that most of your content will be individual lines of code – each line being a route in your application. You’ll find five main types of content in this file:

• RESTful Routes
• Named Routes
• Nested Routes
• Regular Routes
• Default Routes

Each of these types of route is covered in more detail later in this guide.

The routes.rb file is processed from top to bottom when a request comes in. The request will be dispatched to the first matching route. If there is no matching route, then Rails returns HTTP status 404 to the caller.

2.2 RESTful Routes

RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information in a single declaration. A RESTful route looks like this:

2.3 Named Routes

Named routes give you very readable links in your code, as well as handling incoming requests. Here’s a typical named route:

2.4 Nested Routes

Nested routes let you declare that one resource is contained within another resource. You’ll see later on how this translates to URLs and paths in your code. For example, if your application includes parts, each of which belongs to an assembly, you might have this nested route declaration:

2.5 Regular Routes

In many applications, you’ll also see non-RESTful routing, which explicitly connects the parts of a URL to a particular action. For example,

2.6 Default Routes

The default routes are a safety net that catch otherwise-unrouted requests. Many Rails applications will contain this pair of default routes:

These default routes are automatically generated when you create a new Rails application. If you’re using RESTful routing for everything in your application, you will probably want to remove them. But be sure you’re not using the default routes before you remove them!

3 RESTful Routing: the Rails Default

RESTful routing is the current standard for routing in Rails, and it’s the one that you should prefer for new applications. It can take a little while to understand how RESTful routing works, but it’s worth the effort; your code will be easier to read and you’ll be working with Rails, rather than fighting against it, when you use this style of routing.

3.1 What is REST?

The foundation of RESTful routing is generally considered to be Roy Fielding’s doctoral thesis, Architectural Styles and the Design of Network-based Software Architectures. Fortunately, you need not read this entire document to understand how REST works in Rails. REST, an acronym for Representational State Transfer, boils down to two main principles for our purposes:

• Using resource identifiers (which, for the purposes of discussion, you can think of as URLs) to represent resources
• Transferring representations of the state of that resource between system components.

For example, to a Rails application a request such as this:

DELETE /photos/17

would be understood to refer to a photo resource with the ID of 17, and to indicate a desired action – deleting that resource. REST is a natural style for the architecture of web applications, and Rails makes it even more natural by using conventions to shield you from some of the RESTful complexities.

3.2 CRUD, Verbs, and Actions

In Rails, a RESTful route provides a mapping between HTTP verbs, controller actions, and (implicitly) CRUD operations in a database. A single entry in the routing file, such as

creates seven different routes in your application:

HTTP verb	URL	controller	action	used for
GET	/photos	Photos	index	display a list of all photos
GET	/photos/new	Photos	new	return an HTML form for creating a new photo
POST	/photos	Photos	create	create a new photo
GET	/photos/1	Photos	show	display a specific photo
GET	/photos/1/edit	Photos	edit	return an HTML form for editing a photo
PUT	/photos/1	Photos	update	update a specific photo
DELETE	/photos/1	Photos	destroy	delete a specific photo

For the specific routes (those that reference just a single resource), the identifier for the resource will be available within the corresponding controller action as params[:id].

3.3 URLs and Paths

Creating a RESTful route will also make available a pile of helpers within your application:

• photos_url and photos_path map to the path for the index and create actions
• new_photo_url and new_photo_path map to the path for the new action
• edit_photo_url and edit_photo_path map to the path for the edit action
• photo_url and photo_path map to the path for the show, update, and destroy actions

In each case, the _url helper generates a string containing the entire URL that the application will understand, while the _path helper generates a string containing the relative path from the root of the application. For example:

3.4 Defining Multiple Resources at the Same Time

If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to map.resources:

This has exactly the same effect as

3.5 Singular Resources

You can also apply RESTful routing to singleton resources within your application. In this case, you use map.resource instead of map.resources and the route generation is slightly different. For example, a routing entry of

creates six different routes in your application:

HTTP verb	URL	controller	action	used for
GET	/geocoder/new	Geocoders	new	return an HTML form for creating the new geocoder
POST	/geocoder	Geocoders	create	create the new geocoder
GET	/geocoder	Geocoders	show	display the one and only geocoder resource
GET	/geocoder/edit	Geocoders	edit	return an HTML form for editing the geocoder
PUT	/geocoder	Geocoders	update	update the one and only geocoder resource
DELETE	/geocoder	Geocoders	destroy	delete the geocoder resource

A singular RESTful route generates an abbreviated set of helpers:

• new_geocoder_url and new_geocoder_path map to the path for the new action
• edit_geocoder_url and edit_geocoder_path map to the path for the edit action
• geocoder_url and geocoder_path map to the path for the create, show, update, and destroy actions

3.6 Customizing Resources

Although the conventions of RESTful routing are likely to be sufficient for many applications, there are a number of ways to customize the way that RESTful routes work. These options include:

• :controller
• :singular
• :requirements
• :conditions
• :as
• :path_names
• :path_prefix
• :name_prefix
• :only
• :except

You can also add additional routes via the :member and :collection options, which are discussed later in this guide.

3.6.1 Using :controller

The :controller option lets you use a controller name that is different from the public-facing resource name. For example, this routing entry:

will recognize incoming URLs containing photo but route the requests to the Images controller:

HTTP verb	URL	controller	action	used for
GET	/photos	Images	index	display a list of all images
GET	/photos/new	Images	new	return an HTML form for creating a new image
POST	/photos	Images	create	create a new image
GET	/photos/1	Images	show	display a specific image
GET	/photos/1/edit	Images	edit	return an HTML form for editing a image
PUT	/photos/1	Images	update	update a specific image
DELETE	/photos/1	Images	destroy	delete a specific image

3.7 Controller Namespaces and Routing

Rails allows you to group your controllers into namespaces by saving them in folders underneath app/controllers. The :controller option provides a convenient way to use these routes. For example, you might have a resource whose controller is purely for admin users in the admin folder:

If you use controller namespaces, you need to be aware of a subtlety in the Rails routing code: it always tries to preserve as much of the namespace from the previous request as possible. For example, if you are on a view generated from the adminphoto_path helper, and you follow a link generated with <%= link_to "show", adminphoto(1) %> you will end up on the view generated by admin/photos/show, but you will also end up in the same place if you have <%= link_to "show", {:controller => "photos", :action => "show"} %> because Rails will generate the show URL relative to the current URL.

You can also specify a controller namespace with the :namespace option instead of a path:

This can be especially useful when combined with with_options to map multiple namespaced routes together:

That would give you routing for admin/photos and admin/videos controllers.

3.7.1 Using :singular

If for some reason Rails isn’t doing what you want in converting the plural resource name to a singular name in member routes, you can override its judgment with the :singular option:

3.7.2 Using :requirements

You can use the :requirements option in a RESTful route to impose a format on the implied :id parameter in the singular routes. For example:

This declaration constrains the :id parameter to match the supplied regular expression. So, in this case, /photos/1 would no longer be recognized by this route, but /photos/RR27 would.

3.7.3 Using :conditions

Conditions in Rails routing are currently used only to set the HTTP verb for individual routes. Although in theory you can set this for RESTful routes, in practice there is no good reason to do so. (You’ll learn more about conditions in the discussion of classic routing later in this guide.)

3.7.4 Using :as

The :as option lets you override the normal naming for the actual generated paths. For example:

will recognize incoming URLs containing image but route the requests to the Photos controller:

HTTP verb	URL	controller	action	_:used for
GET	/images	Photos	index	display a list of all photos
GET	/images/new	Photos	new	return an HTML form for creating a new photo
POST	/images	Photos	create	create a new photo
GET	/images/1	Photos	show	display a specific photo
GET	/images/1/edit	Photos	edit	return an HTML form for editing a photo
PUT	/images/1	Photos	update	update a specific photo
DELETE	/images/1	Photos	destroy	delete a specific photo

3.7.5 Using :path_names

The :path_names option lets you override the automatically-generated “new” and “edit” segments in URLs:

This would cause the routing to recognize URLs such as

/photos/make
/photos/1/change

3.7.6 Using :path_prefix

The :path_prefix option lets you add additional parameters that will be prefixed to the recognized paths. For example, suppose each photo in your application belongs to a particular photographer. In that case, you might declare this route:

Routes recognized by this entry would include:

/photographers/1/photos/2
/photographers/1/photos

3.7.7 Using :name_prefix

You can use the :name_prefix option to avoid collisions between routes. This is most useful when you have two resources with the same name that use :path_prefix to map differently. For example:

This combination will give you route helpers such as photographer_photos_path and agency_edit_photo_path to use in your code.

3.7.8 Using :only and :except

By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the :only and :except options to fine-tune this behavior. The :only option specifies that only certain routes should be generated:

With this declaration, a GET request to /photos would succeed, but a POST request to /photos (which would ordinarily be routed to the create action) will fail.

The :except option specifies a route or list of routes that should not be generated:

In this case, all of the normal routes except the route for destroy (a DELETE request to /photos/id) will be generated.

In addition to an action or a list of actions, you can also supply the special symbols :all or :none to the :only and :except options.

3.8 Nested Resources

It’s common to have resources that are logically children of other resources. For example, suppose your application includes these models:

Each ad is logically subservient to one magazine. Nested routes allow you to capture this relationship in your routing. In this case, you might include this route declaration:

In addition to the routes for magazines, this declaration will also create routes for ads, each of which requires the specification of a magazine in the URL:

HTTP verb	URL	controller	action	used for
GET	/magazines/1/ads	Ads	index	display a list of all ads for a specific magazine
GET	/magazines/1/ads/new	Ads	new	return an HTML form for creating a new ad belonging to a specific magazine
POST	/magazines/1/ads	Ads	create	create a new ad belonging to a specific magazine
GET	/magazines/1/ads/1	Ads	show	display a specific ad belonging to a specific magazine
GET	/magazines/1/ads/1/edit	Ads	edit	return an HTML form for editing an ad belonging to a specific magazine
PUT	/magazines/1/ads/1	Ads	update	update a specific ad belonging to a specific magazine
DELETE	/magazines/1/ads/1	Ads	destroy	delete a specific ad belonging to a specific magazine

This will also create routing helpers such as magazine_ads_url and edit_magazine_ad_path.

3.8.1 Using :name_prefix

The :name_prefix option overrides the automatically-generated prefix in nested route helpers. For example,

This will create routing helpers such as periodical_ads_url and periodical_edit_ad_path. You can even use :name_prefix to suppress the prefix entirely:

This will create routing helpers such as ads_url and edit_ad_path. Note that calling these will still require supplying an article id:

3.8.2 Using :has_one and :has_many

The :has_one and :has_many options provide a succinct notation for simple nested routes. Use :has_one to nest a singleton resource, or :has_many to nest a plural resource:

This has the same effect as this set of declarations:

3.8.3 Limits to Nesting

You can nest resources within other nested resources if you like. For example:

However, without the use of name_prefix => nil, deeply-nested resources quickly become cumbersome. In this case, for example, the application would recognize URLs such as

/publishers/1/magazines/2/photos/3

The corresponding route helper would be publisher_magazine_photo_url, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular article by Jamis Buck proposes a rule of thumb for good Rails design:

3.8.4 Shallow Nesting

The :shallow option provides an elegant solution to the difficulties of deeply-nested routes. If you specify this option at any level of routing, then paths for nested resources which reference a specific member (that is, those with an :id parameter) will not use the parent path prefix or name prefix. To see what this means, consider this set of routes:

This will enable recognition of (among others) these routes:

/publishers/1           ==> publisher_path(1)
/publishers/1/magazines ==> publisher_magazines_path(1)
/magazines/2            ==> magazine_path(2)
/magazines/2/photos     ==> magazines_photos_path(2)
/photos/3               ==> photo_path(3)

With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with. If you like, you can combine shallow nesting with the :has_one and :has_many options:

3.9 Route Generation from Arrays

In addition to using the generated routing helpers, Rails can also generate RESTful routes from an array of parameters. For example, suppose you have a set of routes generated with these entries in routes.rb:

Rails will generate helpers such as magazine_ad_path that you can use in building links:

Another way to refer to the same route is with an array of objects:

This format is especially useful when you might not know until runtime which of several types of object will be used in a particular link.

3.10 Namespaced Resources

It’s possible to do some quite complex things by combining :path_prefix and :name_prefix. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:

The good news is that if you find yourself using this level of complexity, you can stop. Rails supports namespaced resources to make placing resources in their own folder a snap. Here’s the namespaced version of those same three routes:

As you can see, the namespaced version is much more succinct than the one that spells everything out – but it still creates the same routes. For example, you’ll get admin_photos_url that expects to find an Admin::PhotosController and that matches admin/photos, and admin_photos_ratings_path that matches /admin/photos/_photo_id_/ratings, expecting to use Admin::RatingsController. Even though you’re not specifying path_prefix explicitly, the routing code will calculate the appropriate path_prefix from the route nesting.

3.11 Adding More RESTful Actions

You are not limited to the seven routes that RESTful routing creates by default. If you like, you may add additional member routes (those which apply to a single instance of the resource), additional new routes (those that apply to creating a new resource), or additional collection routes (those which apply to the collection of resources as a whole).

3.11.1 Adding Member Routes

To add a member route, use the :member option:

This will enable Rails to recognize URLs such as /photos/1/preview using the GET HTTP verb, and route them to the preview action of the Photos controller. It will also create a preview_photo route helper.

Within the hash of member routes, each route name specifies the HTTP verb that it will recognize. You can use :get, :put, :post, :delete, or :any here. You can also specify an array of methods, if you need more than one but you don’t want to allow just anything:

3.11.2 Adding Collection Routes

To add a collection route, use the :collection option:

This will enable Rails to recognize URLs such as /photos/search using the GET HTTP verb, and route them to the search action of the Photos controller. It will also create a search_photos route helper.

Just as with member routes, you can specify an array of methods for a collection route:

3.11.3 Adding New Routes

To add a new route (one that creates a new resource), use the :new option:

This will enable Rails to recognize URLs such as /photos/upload using the POST HTTP verb, and route them to the upload action of the Photos controller. It will also create a upload_photos route helper.

3.11.4 A Note of Caution

If you find yourself adding many extra actions to a RESTful route, it’s time to stop and ask yourself whether you’re disguising the presence of another resource that would be better split off on its own. When the :member and :collection hashes become a dumping-ground, RESTful routes lose the advantage of easy readability that is one of their strongest points.

4 Regular Routes

In addition to RESTful routing, Rails supports regular routing – a way to map URLs to controllers and actions. With regular routing, you don’t get the masses of routes automatically generated by RESTful routing. Instead, you must set up each route within your application separately.

While RESTful routing has become the Rails standard, there are still plenty of places where the simpler regular routing works fine. You can even mix the two styles within a single application. In general, you should prefer RESTful routing when possible, because it will make parts of your application easier to write. But there’s no need to try to shoehorn every last piece of your application into a RESTful framework if that’s not a good fit.

4.1 Bound Parameters

When you set up a regular route, you supply a series of symbols that Rails maps to parts of an incoming HTTP request. Two of these symbols are special: :controller maps to the name of a controller in your application, and :action maps to the name of an action within that controller. For example, consider one of the default Rails routes:

If an incoming request of /photos/show/1 is processed by this route (because it hasn’t matched any previous route in the file), then the result will be to invoke the show action of the Photos controller, and to make the final parameter (1) available as params[:id].

4.2 Wildcard Components

You can set up as many wildcard symbols within a regular route as you like. Anything other than :controller or :action will be available to the matching action as part of the params hash. So, if you set up this route:

An incoming URL of /photos/show/1/2 will be dispatched to the show action of the Photos controller. params[:id] will be set to 1, and params[:user_id] will be set to 2.

4.3 Static Text

You can specify static text when creating a route. In this case, the static text is used only for matching the incoming requests:

This route would respond to URLs such as /photos/show/1/with_user/2.

4.4 Querystring Parameters

Rails routing automatically picks up querystring parameters and makes them available in the params hash. For example, with this route:

An incoming URL of /photos/show/1?user_id=2 will be dispatched to the show action of the Photos controller. params[:id] will be set to 1, and params[:user_id] will be equal to 2.

4.5 Defining Defaults

You do not need to explicitly use the :controller and :action symbols within a route. You can supply defaults for these two parameters in a hash:

With this route, an incoming URL of /photos/12 would be dispatched to the show action within the Photos controller.

You can also define other defaults in a route by supplying a hash for the :defaults option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:

With this route, an incoming URL of photos/12 would be dispatched to the show action within the Photos controller, and params[:format] will be set to jpg.

4.6 Named Routes

Regular routes need not use the connect method. You can use any other name here to create a named route. For example,

This will do two things. First, requests to /logout will be sent to the destroy method of the Sessions controller. Second, Rails will maintain the logout_path and logout_url helpers for use within your code.

4.7 Route Requirements

You can use the :requirements option to enforce a format for any parameter in a route:

This route would respond to URLs such as /photo/A12345. You can more succinctly express the same route this way:

4.8 Route Conditions

Route conditions (introduced with the :conditions option) are designed to implement restrictions on routes. Currently, the only supported restriction is :method:

As with conditions in RESTful routes, you can specify :get, :post, :put, :delete, or :any for the acceptable method.

4.9 Route Globbing

Route globbing is a way to specify that a particular parameter should be matched to all the remaining parts of a route. For example

This route would match photo/12 or /photo/long/path/to/12 equally well, creating an array of path segments as the value of params[:other].

4.10 Route Options

You can use :with_options to simplify defining groups of similar routes:

The importance of map.with_options has declined with the introduction of RESTful routes.

5 Formats and respond_to

There’s one more way in which routing can do different things depending on differences in the incoming HTTP request: by issuing a response that corresponds to what the request specifies that it will accept. In Rails routing, you can control this with the special :format parameter in the route.

For instance, consider the second of the default routes in the boilerplate routes.rb file:

This route matches requests such as /photo/edit/1.xml or /photo/show/2.rss. Within the appropriate action code, you can issue different responses depending on the requested format:

5.1 Specifying the Format with an HTTP Header

If there is no :format parameter in the route, Rails will automatically look at the HTTP Accept header to determine the desired format.

5.2 Recognized MIME types

By default, Rails recognizes html, text, json, csv, xml, rss, atom, and yaml as acceptable response types. If you need types beyond this, you can register them in your environment:

6 The Default Routes

When you create a new Rails application, routes.rb is initialized with two default routes:

These routes provide reasonable defaults for many URLs, if you’re not using RESTful routing.

7 The Empty Route

Don’t confuse the default routes with the empty route. The empty route has one specific purpose: to route requests that come in to the root of the web site. For example, if your site is example.com, then requests to http://example.com or http://example.com/ will be handled by the empty route.

7.1 Using map.root

The preferred way to set up the empty route is with the map.root command:

The use of the root method tells Rails that this route applies to requests for the root of the site.

For better readability, you can specify an already-created route in your call to map.root:

Because of the top-down processing of the file, the named route must be specified before the call to map.root.

7.2 Connecting the Empty String

You can also specify an empty route by explicitly connecting the empty string:

8 Inspecting and Testing Routes

Routing in your application should not be a “black box” that you never open. Rails offers built-in tools for both inspecting and testing routes.

8.1 Seeing Existing Routes with rake

If you want a complete list of all of the available routes in your application, run the rake routes command. This will dump all of your routes to the console, in the same order that they appear in routes.rb. For each route, you’ll see:

• The route name (if any)
• The HTTP verb used (if the route doesn’t respond to all verbs)
• The URL pattern
• The routing parameters that will be generated by this URL

For example, here’s a small section of the rake routes output for a RESTful route:

          users GET  /users          {:controller=>"users", :action=>"index"}
formatted_users GET  /users.:format  {:controller=>"users", :action=>"index"}
                POST /users          {:controller=>"users", :action=>"create"}
                POST /users.:format  {:controller=>"users", :action=>"create"}

8.2 Testing Routes

Routes should be included in your testing strategy (just like the rest of your application). Rails offers three built-in assertions designed to make testing routes simpler:

• assert_generates
• assert_recognizes
• assert_routing

8.2.1 The assert_generates Assertion

Use assert_generates to assert that a particular set of options generate a particular path. You can use this with default routes or custom routes

8.2.2 The assert_recognizes Assertion

The assert_recognizes assertion is the inverse of assert_generates. It asserts that Rails recognizes the given path and routes it to a particular spot in your application.

You can supply a :method argument to specify the HTTP verb:

You can also use the RESTful helpers to test recognition of a RESTful route:

8.2.3 The assert_routing Assertion

The assert_routing assertion checks the route both ways: it tests that the path generates the options, and that the options generate the path. Thus, it combines the functions of assert_generates and assert_recognizes.

9 Changelog

Lighthouse ticket

• October 4, 2008: Added additional detail on specifying verbs for resource member/collection routes, by Mike Gunderloy
• September 23, 2008: Added section on namespaced controllers and routing, by Mike Gunderloy
• September 10, 2008: initial version by Mike Gunderloy