Here's an example routes.rb file to give you an idea of how the DSL works:

Notes::Application.routes.draw do
  root :to => "notes#index"

  get "color/:hexcode" => "colors#show"

  resources "notes"

  controller "site_info" do
    get "faq"
    get "contact"
  end
end

This code shows a few different ways you can define routes in Rails. If multiple routes end up matching the same request, the one defined higher up in the file will be given priority. We can see a listing of the resulting routes by running rake routes:

     root        /                         notes#index
          GET    /color/:hexcode(.:format) colors#show
    notes GET    /notes(.:format)          notes#index
          POST   /notes(.:format)          notes#create
 new_note GET    /notes/new(.:format)      notes#new
edit_note GET    /notes/:id/edit(.:format) notes#edit
     note GET    /notes/:id(.:format)      notes#show
          PUT    /notes/:id(.:format)      notes#update
          DELETE /notes/:id(.:format)      notes#destroy
      faq GET    /faq(.:format)            site_info#faq
  contact GET    /contact(.:format)        site_info#contact

$ rake routes CONTROLLER=orders

The listing shows you the name of the route if it has one, followed by the HTTP verb and path pattern it's triggered by, and finally the controller action assigned to handle matching requests. There are a couple of new syntaxes to learn here: one to describe patterns of request paths, and one to specify a controller action.

You can see both of these syntaxes used in the example routes.rb above. The root method is using the string "notes#index" to route the application's root path ("/") to the index action of NotesController. The next line uses the path pattern "color/:hexcode" to match any two-segment path where the first segment is "color".

Notice that the humble resources :notes line is actually responsible for generating the majority of the routes here. Resources are powerful abstractions and they are the recommended way to do most of your routing in Rails.

The controller "site_info" block defines a couple of routes which are both handled by the same controller. Each route definition in there is relying on some syntax conventions in the DSL which mean that a static, single-segment path pattern (such as "faq" or "contact") is assumed to double as the name of the action being routed to, unless a different action is specified.

It may seem strange that the optional (.:format) segment is included on all the routes, even though it was never specified in routes.rb. Rails does this to provide a standardized way of accessing the same URIs in different formats (.html, .json, or whatever else your controller action is written to handle).

The conventional way of configuring routes for a Rails application is to build everything around resources. A resource is an entity that you expose to the outside world at a particular URI. If someone wants to access one of your application's resources, they send your application a request using one of the HTTP verbs. If they just want to see the resource, they use GET. If they want to update it, they use PUT. POST is for creating new resources, and DELETE is for destroying them.

In Rails, resources are declared in the routing system and implemented as actions in a controller whose job it is to handle that one kind of resource. Here's how you'd define routes for an orders resource:

You always need to define your routes within the routes.draw block, but for simplicity and succinctness we'll only be showing the contents of the draw block in the upcoming examples.

resources :orders

As you can see from the output of rake routes, the resources :orders definition generates seven routes for you:

$ rake routes

           GET    /orders(.:format)          {:controller=>"orders", :action=>"index"}
    orders POST   /orders(.:format)          {:controller=>"orders", :action=>"create"}
 new_order GET    /orders/new(.:format)      {:controller=>"orders", :action=>"new"}
           GET    /orders/:id(.:format)      {:controller=>"orders", :action=>"show"}
           PUT    /orders/:id(.:format)      {:controller=>"orders", :action=>"update"}
     order DELETE /orders/:id(.:format)      {:controller=>"orders", :action=>"destroy"}
edit_order GET    /orders/:id/edit(.:format) {:controller=>"orders", :action=>"edit"}

There are two main path patterns being matched here: /orders (the collection URI) and /orders/:id (the member or element URI). Each is routed to a different controller action depending on which HTTP verb is being used. In addition, the new_order and edit_order routes are mapped to special actions which have their own unique URIs relative to the collection and member paths, respectively.

So, what should all these controller actions do? It's up to you how you implement these behaviours in the controllers, but here's a rundown of the conventional approach:

def show
  @user = User.find_by_nickname!(params[:id])
  respond_with(@user)
end

resources "users", :param => :nickname   # get it with params[:nickname]

If you only want a resource to respond to some of the above actions but not others, you can use the :only option. For example, you might have a read-only resource:

resources "fibonacci_numbers", :only => ["index", "show"]

resources "templates" do
  member do
    get "render"    # GET /templates/:id/render
  end
  collection do
    get "count"     # GET /templates/count
    put "reorder"   # PUT /templates/reorder
  end
end

resources "templates" do
  get "render",  :on => :member
  get "count",   :on => :collection
  put "reorder", :on => :collection
end

resources "articles" do
  collection do
    get ":author", :action => "index"
  end
end

resource :account

$ rake routes

             POST   /account(.:format)      {:controller=>"accounts", :action=>"create"}
 new_account GET    /account/new(.:format)  {:controller=>"accounts", :action=>"new"}
             GET    /account(.:format)      {:controller=>"accounts", :action=>"show"}
             PUT    /account(.:format)      {:controller=>"accounts", :action=>"update"}
     account DELETE /account(.:format)      {:controller=>"accounts", :action=>"destroy"}
edit_account GET    /account/edit(.:format) {:controller=>"accounts", :action=>"edit"}

resource  :account
resources :accounts

resources :orders do
  resources :line_items
end

$ rake routes

                     GET    /orders/:order_id/line_items(.:format)          {:controller=>"line_items", :action=>"index"}
    order_line_items POST   /orders/:order_id/line_items(.:format)          {:controller=>"line_items", :action=>"create"}
 new_order_line_item GET    /orders/:order_id/line_items/new(.:format)      {:controller=>"line_items", :action=>"new"}
                     GET    /orders/:order_id/line_items/:id(.:format)      {:controller=>"line_items", :action=>"show"}
                     PUT    /orders/:order_id/line_items/:id(.:format)      {:controller=>"line_items", :action=>"update"}
     order_line_item DELETE /orders/:order_id/line_items/:id(.:format)      {:controller=>"line_items", :action=>"destroy"}
edit_order_line_item GET    /orders/:order_id/line_items/:id/edit(.:format) {:controller=>"line_items", :action=>"edit"}
                     GET    /orders(.:format)                               {:controller=>"orders", :action=>"index"}
              orders POST   /orders(.:format)                               {:controller=>"orders", :action=>"create"}
           new_order GET    /orders/new(.:format)                           {:controller=>"orders", :action=>"new"}
                     GET    /orders/:id(.:format)                           {:controller=>"orders", :action=>"show"}
                     PUT    /orders/:id(.:format)                           {:controller=>"orders", :action=>"update"}
               order DELETE /orders/:id(.:format)                           {:controller=>"orders", :action=>"destroy"}
          edit_order GET    /orders/:id/edit(.:format)                      {:controller=>"orders", :action=>"edit"}

resources :orders do
  resource :shipping_address
end

$ rake routes

                            POST   /orders/:order_id/shipping_address(.:format)      {:controller=>"shipping_addresses", :action=>"create"}
 new_order_shipping_address GET    /orders/:order_id/shipping_address/new(.:format)  {:controller=>"shipping_addresses", :action=>"new"}
                            GET    /orders/:order_id/shipping_address(.:format)      {:controller=>"shipping_addresses", :action=>"show"}
                            PUT    /orders/:order_id/shipping_address(.:format)      {:controller=>"shipping_addresses", :action=>"update"}
     order_shipping_address DELETE /orders/:order_id/shipping_address(.:format)      {:controller=>"shipping_addresses", :action=>"destroy"}
edit_order_shipping_address GET    /orders/:order_id/shipping_address/edit(.:format) {:controller=>"shipping_addresses", :action=>"edit"}
                            GET    /orders(.:format)                                 {:controller=>"orders", :action=>"index"}
                     orders POST   /orders(.:format)                                 {:controller=>"orders", :action=>"create"}
                  new_order GET    /orders/new(.:format)                             {:controller=>"orders", :action=>"new"}
                            GET    /orders/:id(.:format)                             {:controller=>"orders", :action=>"show"}
                            PUT    /orders/:id(.:format)                             {:controller=>"orders", :action=>"update"}
                      order DELETE /orders/:id(.:format)                             {:controller=>"orders", :action=>"destroy"}
                 edit_order GET    /orders/:id/edit(.:format)                        {:controller=>"orders", :action=>"edit"}

The same methods used to make custom actions for resources can be used to make standalone routes that match whatever patterns you can dream up. This section describes in greater detail how to create create individual routes, whether or not they are scoped to a resource.

Maybe we just want an "about us" page with no fuss. Okay, assuming we have a PagesController with an about action:

get "about" => "pages#about"

We don't really need to specify the action in this case, because Rails makes the assumption that a fixed single-segment path pattern is the action name unless otherwise specified. On the other hand, there's definitely something to be said for being explicit. The following lines all define equivalent routes:

# all of these routes lead to PagesController#about:
get "about" => "pages#about"
get "about" => "pages"
get "about", :to => "pages#about"
get "about", :to => "pages"
get "about", :controller => "pages"

If you want your route to match some other HTTP method, that works too:

post "webhooks/github_post_receive"

In this case, because we've provided a fixed two-segment pattern, Rails will assume that the first segment is the controller name and the second segment is the action.

match "big-red-button", :to => "control_panel#button", :via => [:get, :post]

# but really, this should use resources:
get  "big-red-button" => "control_panel#show_button"
post "big-red-button" => "control_panel#push_button"

get "color/:hexcode" => "colors#show"

get "welcome" => "pages", :format => false
# /welcome.json or /welcome.html would not match this route

get "articles(/:author(/:topic))" => "articles#index"

get "articles/*tags" => "articles#index"

get "articles/*tags/:last_tag" => "articles#index"

# gives you the following params:
# {
#   "controller" => "articles",
#   "action" => "index",
#   "tags" => "silly/politics",
#   "last_tag" => "facepalm"
# }

When defining routes that contain optional named parameters, it is useful to be able to define a default value for the optional parameter in the route for when it isn't provided. A hash of defaults can be passed to the route definition itself or you can specify routes within a defaults block.

Defaults are passed by name as additional options to the routing definition. For example, to set a default :handle parameter when none is provided, the route would look as follows:

get "pages(/:handle)", :to => "pages#show", :handle => "home"

With the default provided for :handle, whenever the path /pages is requested the :handle parameter will be set to home. To specify defaults for multiple routes you can pass the defaults to the defaults method and define all routes that you want the defaults to apply to within the block passed to the defaults method:

defaults :handle => "home" do
  get "pages(/:handle)"    => "pages#show"
  get "articles(/:handle)" => "articles#show"
end

Parameter defaults work for any route definition, not just ones with optional path segments:

get "apps", :to => "apps#index", :filter => "featured"

The :filter param can then be overridden in the query string, as in /apps?filter=all. In a case like this, though, you'd probably want to define the default value in the controller action code; that's the first place people will look if they're trying to figure out how the response is constructed.

If you want to limit a dynamic segment to a specific pattern of characters, you can use the :constraints option, which takes a hash of segment params mapped to regular expressions:

get "color/:hexcode" => "colors#show",
  :constraints => {:hexcode => /[A-Fa-f0-9]{6}/}

The regular expressions are automatically wrapped in beginning- and end-of-string anchors, so you should leave out any anchors of your own (^, $, \A, \Z, or \z). In fact if you try to include them, you'll get an ArgumentError.

You can also easily place constraints on attributes of the incoming request. You can use regular expressions just like segment constraints, but you'll often just want to match a particular string:

get "secrets" => "secrets#index",
  :constraints => {:subdomain => "admin"}

Any of the public methods on the request object which return strings are fair game here. For more information about request objects in Rails, see ???.

If you want to go beyond regular expressions, you can. To bring out the big guns, you have to skip the regex hash and supply the :constraints option with one of two things: an object that implements a matches? method, or a callable object like a Proc.

The first way is probably the most common, and the most straightforward approach is to define a little class above your routes, like so:

class SpecialConstraint
  def matches?(request)
    request.headers.key?("X-Special")
  end
end

MyApp::Application.routes.draw do
  get "foo" => "special#foo", :constraints => SpecialConstraint.new
  get "foo" => "boring#foo"
end

The matches? method must take a single argument (the request object), and it should return true or false to indicate a matching or non-matching request. Here we have two routes matching the same path, but they get switched between based on HTTP request headers. Because the constrained route is defined first, the "boring" route ends up as the fallback.

The above logic is simple enough that you could also go the other route and use a Proc object (instantiated here with lambda):

get "foo" => "special#foo",
  :constraints => (lambda {|req| req.headers.key?("X-Special")})

constraints :subdomain => "begins-with-j", :name => /[Jj]\w*/ do
  get "people/:name" => "people#show"
  get "places/:name" => "places#show"
end

Named routes are essentially the same as routes defined using match in that they match incoming URIs to controller actions. The advantage of named routes is that they provide you with some additional helpers that can be used in your controllers and views. Each named route provides you with two helpers of the form name_url and name_path, where name is the name you've given the named route. For example, if we generate the following named route:

match 'orders' => 'orders#index', :as => 'orders'

$ rake routes

orders  /orders {:controller=>"orders", :action=>"index"}

You then have access to orders_url and orders_path helpers in your controllers and views.

users_url  #=> "http://localhost:3000/users"
users_path #=> "/users"

The root route tells your application which controller and action to send requests to the root of your application. The root route is defined as follows:

root :to => 'dashboard#index'

$ rake routes

root  / {:controller=>"dashboard", :action=>"index"}

In this example we're routing the root URI of the application to the index action of the DashboardController. A named route is also defined for the root route, which provides you with root_url and root_path

Basically every time you see a block in the routing DSL, there's a scope behind the scenes working its magic. Scopes wrap multiple routes in a block, letting you do a few very useful things to all the enclosed routes at once:

A resources block makes use of all of these capabilities in a rather complicated way to make everything work. A constraints block, on the other hand, simply sets a default value for the :constraints option on the enclosed routes.

You can craft your own scopes with the scope method. Dealing with default route options is pretty straightforward:

scope :controller => "forest" do
  get "trees"
  get "bears"
end

To use a common prefix for your routes' path patterns, use the :path option or just provide a string as the first argument like you'd do with a single route definition. The prefix can use dynamic and optional segments just like the routes themselves do. Here's a routes file for an application where any path can be prefixed with an optional segment to select the locale code:

Localized::Application.routes.draw do
  constraints :locale => /[a-z]{2}(-[A-Z]{2})?/ do
    scope "(:locale)" do
      root :to => "welcome#index"

      resources "users", "locales", "articles"
    end
  end
end

Note that without the constraints on :locale, the path /users would be routed to "welcome#index" because "users" would match as the locale. Be careful when you have a dynamic segment at the beginning of a path; it's more likely to conflict with other routes.

To prefix the names of the enclosed routes, use the :as option. Combined with a custom path, this can be useful for managing different ways of accessing the same resource:

resources "bears"
scope ":emotion", :as => "emotional" do
  resources "bears"
end

This would give you a second set of named resource routes like emotional_bears and new_emotional_bear. For example you could link to /angry/bears with emotional_bears_path(:emotion => "angry").

Scopes are a powerful tool to help you create the routes needed to fit your application's unique requirements. Let's say we have a files resource that we really want to reference by path instead of by numeric id. File paths of course can contain both forward slashes and periods, and they usually end in their own extension. This means that you might want to step away from the Rails conventions a little bit by forgoing the usual trailing (.:format) segment. Here's one way we could do that:

scope "(:format)", :except => [:edit], :constraints => {:id => /.*/} do
  resources "files"
end

The :id constraint overrides the normal delimiters and gives that segment the whole rest of the path for the resource member routes that it's defined in. The :except option gets rid of the edit action on any enclosed resources, because that trailing /edit on the member paths would now just be assumed to be part of the :id segment.

A namespace block is a scope that basically does three things to the routes inside: it prefixes paths, it prefixes names, and it specifies a namespace module where the controllers can be found. For example, let's define the singleton account resource underneath the admin namespace:

namespace :admin do
  resource :account
end

$ rake routes

                   POST   /admin/account(.:format)      {:controller=>"admin/accounts", :action=>"create"}
 new_admin_account GET    /admin/account/new(.:format)  {:controller=>"admin/accounts", :action=>"new"}
                   GET    /admin/account(.:format)      {:controller=>"admin/accounts", :action=>"show"}
                   PUT    /admin/account(.:format)      {:controller=>"admin/accounts", :action=>"update"}
     admin_account DELETE /admin/account(.:format)      {:controller=>"admin/accounts", :action=>"destroy"}
edit_admin_account GET    /admin/account/edit(.:format) {:controller=>"admin/accounts", :action=>"edit"}

As you can see from the rake routes output, the route names, path patterns, and controllers are all namespaced in their own way.

Instead of routing to a controller and action, you can define a route that will issue a permanent redirect to some other location. Rails provides you with a redirect helper method to do this. Here's the simplest case:

match "foo" => redirect("/bar")

Any request for /foo will then get a 301 response redirecting them to /bar instead. If you want to use params from the requested path to construct the new path, you can use the following syntax:

get "old/:tricks" => redirect("/new/%{tricks}")

Passing an options hash instead of a string will only change the specified elements of the URI:

match "/admin(/*whatever)", :constraints => {:protocol => "http://"},
  :to => redirect(:protocol => "https")

You can also pass a block, which takes the params and request object as arguments, and then you can use whatever logic you want:

match "quiet/:something" => redirect {|params, request|
  "/LOUD/#{params[:something].upcase}"
}