module ActionDispatch::Routing::Mapper::Resources

To add a route to the collection:

resources :photos do
  collection do
    get 'search'
  end
end

This will enable Rails to recognize paths such as /photos/search with GET, and route to the search action of PhotosController. It will also create the search_photos_url and search_photos_path route helpers.

Loads another routes file with the given name located inside the config/routes directory. In that file, you can use the normal routing DSL, but do not surround it with a Rails.application.routes.draw block.

# config/routes.rb
Rails.application.routes.draw do
  draw :admin                 # Loads `config/routes/admin.rb`
  draw "third_party/some_gem" # Loads `config/routes/third_party/some_gem.rb`
end

# config/routes/admin.rb
namespace :admin do
  resources :accounts
end

# config/routes/third_party/some_gem.rb
mount SomeGem::Engine, at: "/some_gem"

CAUTION: Use this feature with care. Having multiple routes files can negatively impact discoverability and readability. For most applications —even those with a few hundred routes — it’s easier for developers to have a single routes file.

Matches a URL pattern to one or more routes. For more information, see match.

match 'path' => 'controller#action', via: :patch
match 'path', to: 'controller#action', via: :post
match 'path', 'otherpath', on: :member, via: :get

To add a member route, add a member block into the resource block:

resources :photos do
  member do
    get 'preview'
  end
end

This will recognize /photos/1/preview with GET, and route to the preview action of PhotosController. It will also create the preview_photo_url and preview_photo_path helpers.

See ActionDispatch::Routing::Mapper::Scoping#namespace.

Sometimes, you have a resource that clients always look up without referencing an ID. A common example, /profile always shows the profile of the currently logged in user. In this case, you can use a singular resource to map /profile (rather than /profile/:id) to the show action:

resource :profile

This creates six different routes in your application, all mapping to the Profiles controller (note that the controller is named after the plural):

GET       /profile/new
GET       /profile
GET       /profile/edit
PATCH/PUT /profile
DELETE    /profile
POST      /profile

If you want instances of a model to work with this resource via record identification (e.g. in form_with or redirect_to), you will need to call resolve:

resource :profile
resolve('Profile') { [:profile] }

# Enables this to work with singular routes:
form_with(model: @profile) {}

Options

Takes same options as resources

In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions. By convention, each action also maps to particular CRUD operations in a database. A single entry in the routing file, such as

resources :photos

creates seven different routes in your application, all mapping to the Photos controller:

GET       /photos
GET       /photos/new
POST      /photos
GET       /photos/:id
GET       /photos/:id/edit
PATCH/PUT /photos/:id
DELETE    /photos/:id

Resources can also be nested infinitely by using this block syntax:

resources :photos do
  resources :comments
end

This generates the following comments routes:

GET       /photos/:photo_id/comments
GET       /photos/:photo_id/comments/new
POST      /photos/:photo_id/comments
GET       /photos/:photo_id/comments/:id
GET       /photos/:photo_id/comments/:id/edit
PATCH/PUT /photos/:photo_id/comments/:id
DELETE    /photos/:photo_id/comments/:id

Options

Takes same options as match as well as:

:path_names

Allows you to change the segment component of the edit and new actions. Actions not specified are not changed.

    resources :posts, path_names: { new: "brand_new" }

The above example will now change /posts/new to /posts/brand_new.

:path

Allows you to change the path prefix for the resource.

    resources :posts, path: 'postings'

The resource and all segments will now route to /postings instead of
/posts.

:only

Only generate routes for the given actions.

    resources :cows, only: :show
    resources :cows, only: [:show, :index]

:except

Generate all routes except for the given actions.

    resources :cows, except: :show
    resources :cows, except: [:show, :index]

:shallow

Generates shallow routes for nested resource(s). When placed on a parent resource, generates shallow routes for all nested resources.

    resources :posts, shallow: true do
      resources :comments
    end

Is the same as:

    resources :posts do
      resources :comments, except: [:show, :edit, :update, :destroy]
    end
    resources :comments, only: [:show, :edit, :update, :destroy]

This allows URLs for resources that otherwise would be deeply nested such
as a comment on a blog post like `/posts/a-long-permalink/comments/1234`
to be shortened to just `/comments/1234`.

Set `shallow: false` on a child resource to ignore a parent's shallow
parameter.

:shallow_path

Prefixes nested shallow routes with the specified path.

    scope shallow_path: "sekret" do
      resources :posts do
        resources :comments, shallow: true
      end
    end

The `comments` resource here will have the following routes generated for
it:

    post_comments    GET       /posts/:post_id/comments(.:format)
    post_comments    POST      /posts/:post_id/comments(.:format)
    new_post_comment GET       /posts/:post_id/comments/new(.:format)
    edit_comment     GET       /sekret/comments/:id/edit(.:format)
    comment          GET       /sekret/comments/:id(.:format)
    comment          PATCH/PUT /sekret/comments/:id(.:format)
    comment          DELETE    /sekret/comments/:id(.:format)

:shallow_prefix

Prefixes nested shallow route names with specified prefix.

    scope shallow_prefix: "sekret" do
      resources :posts do
        resources :comments, shallow: true
      end
    end

The `comments` resource here will have the following routes generated for
it:

    post_comments           GET       /posts/:post_id/comments(.:format)
    post_comments           POST      /posts/:post_id/comments(.:format)
    new_post_comment        GET       /posts/:post_id/comments/new(.:format)
    edit_sekret_comment     GET       /comments/:id/edit(.:format)
    sekret_comment          GET       /comments/:id(.:format)
    sekret_comment          PATCH/PUT /comments/:id(.:format)
    sekret_comment          DELETE    /comments/:id(.:format)

:format

Allows you to specify the default value for optional format segment or disable it by supplying false.

:param

Allows you to override the default param name of :id in the URL.

Examples

# routes call +Admin::PostsController+
resources :posts, module: "admin"

# resource actions are at /admin/posts.
resources :posts, path: "admin/posts"

You can specify what Rails should route “/” to with the root method:

root to: 'pages#main'

For options, see match, as root uses it internally.

You can also pass a string which will expand

root 'pages#main'

You should put the root route at the top of config/routes.rb, because this means it will be matched first. As this is the most popular route of most Rails applications, this is beneficial.