How Rails Routing Works: A Complete Guide (Rails 8)

Every Rails developer eventually runs into a moment where a page returns a routing error instead of the page they expected. That moment is usually the first real introduction to one of the most important pieces of the framework: the router. Routing sits at the very front door of every Rails application. Before a controller runs, before a database query fires, before a single line of view code renders, the request has to pass through the router and get matched to a destination.

That is exactly why routing is one of the first concepts every Rails developer should learn well. If you do not understand how Rails routing works, you will spend a lot of time guessing why a link does not work, why a form submits to the wrong place, or why a URL that looks correct returns a 404. Once you understand routing, those problems become easy to diagnose and even easier to avoid.

In this Rails routing tutorial, you will learn how the Rails router works from the moment a browser sends a request all the way through to the controller action that handles it. You will learn how to write RESTful routes with resources, how nested routes work, how to organize related routes with namespaces and scopes, how to add custom member and collection routes, and how to debug routing issues using the tools Rails gives you. By the end, you will be comfortable reading and writing routes.rb files with confidence, using Rails 8 conventions throughout.

What Is Routing in Ruby on Rails?

Routing is the process of mapping an incoming HTTP request to a specific piece of code that should handle it. In a Rails application, that mapping lives in a single file: config/routes.rb. Every URL your application responds to, whether it is a page a user visits in a browser or an API endpoint a mobile app calls, has to be defined somewhere in that file, either explicitly or through a shortcut like resources.

Rails routing fits into the bigger picture of the MVC architecture that Rails is built around. If you are still getting comfortable with how models, views, and controllers work together, it is worth reading our guide on Rails MVC for beginners before going further here, since routing is the piece that decides which controller and action get involved in the first place.

When a request comes in, Rails does not immediately know what to do with it. The Rails router looks at two things: the HTTP verb (GET, POST, PATCH, PUT, or DELETE) and the URL path. It compares that combination against every route defined in routes.rb, in order, until it finds a match. Once it finds one, it hands the request off to the corresponding controller action.

Here is a simple way to visualize that first step:

Incoming Request (GET /articles/5)
            |
            v
      Rails Router
            |
            v
   Match found in routes.rb
            |
            v
  ArticlesController#show

That diagram looks simple, but it represents something powerful. The router is the single source of truth for every URL your application understands. If a route is not defined, Rails will not know what to do with that request, and the user will see a routing error instead of your application logic running.

Understanding the Request Lifecycle

To really understand routing, it helps to zoom out and see the entire journey a request takes, from the moment it leaves the browser to the moment a response comes back. Routing is only one stop along that path, but it is the stop that determines everything that happens afterward.

Here is the full lifecycle, step by step:

1. Browser request. A user clicks a link, submits a form, or types a URL. The browser sends an HTTP request to your server with a verb and a path, for example GET /articles.
2. Rails router. The request hits your Rails application and the router inspects routes.rb to find a matching route.
3. Route matching. Rails compares the verb and path against every route definition, in the order they appear in the file, until it finds a match.
4. Controller. Once a match is found, Rails instantiates the corresponding controller, for example ArticlesController.
5. Action. Rails calls the specific method on that controller that the route pointed to, for example the index action.
6. Model (if needed). Inside the action, the controller often talks to a model to fetch or update data, for example Article.all or Article.find(params[:id]).
7. View. Once the controller has the data it needs, Rails renders the corresponding view template, unless the controller explicitly redirects or renders something else.
8. Response. The final HTML, JSON, or other response format is sent back to the browser.

You can picture the whole flow like this:

Browser
  |
  |  GET /articles/5
  v
Rails Router  ---->  routes.rb
  |
  |  matched route
  v
ArticlesController#show
  |
  |  Article.find(params[:id])
  v
Article Model  ---->  Database
  |
  |  data returned
  v
articles/show.html.erb
  |
  v
HTML Response  ---->  Browser

Notice that routing only handles one job in this whole chain: figuring out which controller and action should run. It does not touch the database, and it does not render anything. Its entire purpose is to be a traffic director. Once you separate that responsibility in your head, a lot of confusion about "is this a routing problem or a controller problem" starts to disappear.

The routes.rb File

Every route in your application is defined inside config/routes.rb. This file lives at the root of your config directory and is loaded automatically when your Rails application boots.

A basic routes.rb file might start out looking like this:

Rails.application.routes.draw do
  get "welcome/index"

  resources :articles

  root "welcome#index"
end

Everything inside the draw do ... end block defines part of your application's routing table. Rails reads this file top to bottom, and that order matters more than a lot of beginners realize.

How routes are evaluated

When a request comes in, Rails walks through the routes in routes.rb in the exact order they are written and stops at the first one that matches both the HTTP verb and the URL pattern. This means that if you define a broad, catch-all route near the top of the file, it can accidentally intercept requests that were meant for a more specific route defined further down.

Here is a simple example of a route order problem:

Rails.application.routes.draw do
  get "articles/:id", to: "articles#show"
  get "articles/featured", to: "articles#featured"
end

In this setup, a request to /articles/featured will actually match the first route, articles/:id, because Rails treats featured as a value for the :id parameter. The articles#featured route will never be reached, because Rails stops looking as soon as it finds a match. The fix is simple: place more specific routes above more general ones.

Rails.application.routes.draw do
  get "articles/featured", to: "articles#featured"
  get "articles/:id", to: "articles#show"
end

Now /articles/featured matches the specific route first, and any other /articles/:id value falls through to the general route. This is a small example, but it represents one of the most common sources of confusing routing bugs in real Rails applications.

RESTful Routing

REST, which stands for Representational State Transfer, is the design philosophy that Rails routing is built around. The idea behind REST is that most web applications deal with resources, things like articles, users, comments, or orders, and that most actions you want to perform on those resources fall into a small, predictable set: viewing a list, viewing one item, creating a new one, editing an existing one, and deleting one.

Rather than making you write out a route for every single one of those actions by hand, Rails gives you the resources method, which generates all of them in one line.

Rails.application.routes.draw do
  resources :articles
end

That single line generates seven routes, each mapped to a specific HTTP verb, URL pattern, controller action, and route helper. Here is the full breakdown:

Let's walk through what each of these actually does.

The index action handles requests to see a full list of articles. The new action renders a blank form for creating a new article, while create is the action that actually receives the submitted form data and saves a new record. The show action displays a single article, edit renders a form pre-filled with an existing article's data, and update receives the submitted changes and saves them. Finally, destroy removes the article.

This one line, resources :articles, is doing the work that would otherwise take seven separate get, post, patch, and delete calls. That is the real value of RESTful routing in Rails: it turns a repetitive, error-prone task into a single, predictable declaration.

Singular vs Plural Resources

Rails gives you two different methods depending on whether a resource can have multiple instances or exactly one: resources for plural, collection-style resources, and resource for singular resources.

Use resources when a user can have many of something, like articles, comments, or products.

resources :articles

Use resource, singular, when there is only ever one of something in a given context, most commonly things tied directly to the current user, like a profile or an account setting.

resource :profile

The difference shows up clearly in the generated routes. With resources :articles, Rails generates routes like /articles/5 because you need an ID to know which article you are talking about. With resource :profile, there is no ID in the URL at all, because there is only one profile in that context, the current user's own profile. The generated path is simply /profile, and the routes it creates skip index entirely, since there is nothing to list.

A common real-world use case is account settings pages. A user does not visit /users/42/profile, they visit /profile, and Rails already knows from the session which profile that refers to. That is exactly the kind of situation where resource, singular, is the right choice.

Route Helpers

One of the most useful things resources gives you is a set of named route helpers. Instead of hardcoding URL strings throughout your application, which becomes a maintenance nightmare the moment a URL structure changes, you use these generated helper methods.

For an articles resource, Rails automatically generates helpers like:

• articles_path and articles_url for the index
• article_path(@article) and article_url(@article) for a single article
• new_article_path for the new article form
• edit_article_path(@article) for the edit form

The difference between the _path and _url versions is simple. _path returns a relative path, like /articles/5, while _url returns the full URL, including protocol and host, like https://codecurious.dev/articles/5. In views and controllers you will almost always reach for _path helpers, since relative paths are all a browser needs when navigating within the same application. The _url versions become important in places like emails or API responses, where the recipient is not already inside your application and needs an absolute link.

Here is how these helpers show up in real code.

In a controller, after creating a new article, you would typically redirect using the helper rather than a hardcoded string:

class ArticlesController < ApplicationController
  def create
    @article = Article.new(article_params)

    if @article.save
      redirect_to article_path(@article), notice: "Article created."
    else
      render :new, status: :unprocessable_entity
    end
  end
end

In a view, you would use the same helpers to build links:

<%= link_to "View Article", article_path(@article) %>
<%= link_to "Edit Article", edit_article_path(@article) %>
<%= link_to "All Articles", articles_path %>

And in forms, Rails uses these same route conventions automatically through form_with:

<%= form_with model: @article do |form| %>
  <%= form.text_field :title %>
  <%= form.submit %>
<% end %>

Rails looks at whether @article is a new or persisted record and automatically points the form at either articles_path with a POST, for a new record, or article_path(@article) with a PATCH, for an existing one. This is also exactly the kind of pattern you will see when working with Turbo Frames, where forms and links inside a frame rely on these same route helpers to know where to submit and navigate. If you have not worked with Turbo Frames yet, our article on how Turbo Frames work in Ruby on Rails is a good next step once you are comfortable with routing basics.

Nested Routes

Nested routes exist to express a parent-child relationship directly in the URL structure. If comments always belong to a specific article, it often makes sense for the URL to reflect that relationship, rather than treating comments as a completely independent, top-level resource.

Here is a blog example with articles and comments:

Rails.application.routes.draw do
  resources :articles do
    resources :comments
  end
end

This generates routes like /articles/5/comments for the comments index and /articles/5/comments/12 for a single comment, along with the full set of new, create, edit, update, and destroy routes underneath that same nested path. The route helpers follow the same nesting pattern: article_comments_path(@article) and article_comment_path(@article, @comment).

Nested routes are a great way to make it explicit, both in the URL and in your controller code, that a comment cannot exist without an article. Inside CommentsController, you would use params[:article_id] to find the parent article before creating or querying comments.

class CommentsController < ApplicationController
  before_action :set_article

  def create
    @comment = @article.comments.new(comment_params)
    if @comment.save
      redirect_to article_path(@article)
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def set_article
    @article = Article.find(params[:article_id])
  end
end

The general best practice here is to nest only one level deep. Nesting comments under articles is reasonable. Nesting replies under comments under articles, producing URLs like /articles/5/comments/12/replies/3, quickly becomes unwieldy and hard to reason about. When you find yourself needing deeper relationships, it is usually better to flatten the structure using shallow routing, which we will cover a bit further down.

Member and Collection Routes

Sometimes the standard seven RESTful actions are not enough. You might need a route to publish an article, archive it, or run a search across all articles. Rails gives you two tools for this: member routes and collection routes.

A member route operates on a single, specific resource, so it needs an ID in the URL. A collection route operates on the resource as a whole, so it does not need an ID.

resources :articles do
  member do
    patch :publish
    patch :archive
  end

  collection do
    get :search
    get :featured
  end
end

This generates /articles/5/publish and /articles/5/archive as member routes, since publishing or archiving only makes sense for one specific article. It also generates /articles/search and /articles/featured as collection routes, since searching or listing featured articles applies to the whole set of articles, not just one.

A simple rule of thumb: if the action needs to know which specific record you are talking about, it belongs under member. If the action applies to the resource as a category rather than a single instance, it belongs under collection.

Namespaces

As applications grow, it becomes useful to group related controllers and routes together, especially for things like admin dashboards. That is exactly what namespace is for.

Rails.application.routes.draw do
  namespace :admin do
    resources :articles
    resources :users
  end
end

This generates routes prefixed with /admin, like /admin/articles and /admin/users, and it expects the corresponding controllers to live inside an Admin module, at app/controllers/admin/articles_controller.rb and app/controllers/admin/users_controller.rb. The route helpers follow the same pattern, becoming admin_articles_path and admin_users_path.

Namespaces are one of the cleanest ways to build an admin dashboard in Rails, because they keep your admin controllers, views, and routes completely separate from your public-facing ones, without any risk of naming collisions. A public ArticlesController and an Admin::ArticlesController can coexist without any conflict at all.

Scope

While namespace changes the URL, the controller module, and the route helper prefix all at once, scope lets you change just one or two of those independently, giving you more fine-grained control.

scope path: "/admin", as: "admin" do
  resources :articles
end

This produces the same URLs as the namespace example, /admin/articles, and the same route helper prefix, admin_articles_path, but it expects the controller to be the regular top-level ArticlesController, not Admin::ArticlesController. This is useful when you want an admin-style URL structure without physically reorganizing your controllers into a separate module.

You can also use scope module: to change only the controller lookup without touching the URL or the helper name at all:

scope module: "admin" do
  resources :articles
end

This keeps the URL as plain /articles and the helper as articles_path, but routes the request to Admin::ArticlesController. And path_names lets you customize the segments Rails uses for actions like new and edit, which is handy if you want URLs in a different language or style.

scope path_names: { new: "nouveau", edit: "modifier" } do
  resources :articles
end

That would turn /articles/new into /articles/nouveau, while keeping the underlying action and helper names exactly the same.

Dynamic Route Segments

Most routes need to identify a specific record, and Rails handles that through dynamic segments, most commonly :id.

get "articles/:id", to: "articles#show"

When a request comes in for /articles/5, Rails extracts 5 and makes it available inside the controller as params[:id].

You are not limited to :id, though. It is common to use a :slug instead, especially for content-heavy sites like blogs, where a friendly URL like /articles/how-rails-routing-works is far more readable and better for SEO than /articles/482.

get "articles/:slug", to: "articles#show"

To support this, you would typically override the to_param method on your model so that route helpers automatically generate slug-based URLs, and then look records up by slug instead of ID in the controller:

class Article < ApplicationRecord
  def to_param
    slug
  end
end

class ArticlesController < ApplicationController
  def show
    @article = Article.find_by!(slug: params[:slug])
  end
end

This small change means every article_path(@article) call throughout your application automatically produces a friendly, slug-based URL, without you having to change a single view.

Constraints

Constraints let you restrict when a route matches, based on things like the format of a parameter, the subdomain of the request, or the requested response format.

A common use case is restricting an :id segment to only match numeric values, so it does not accidentally swallow up other routes:

get "articles/:id", to: "articles#show", constraints: { id: /\d+/ }

Subdomain constraints are useful for multi-tenant applications, where different subdomains might route to completely different logic:

constraints subdomain: "admin" do
  resources :articles
end

Format constraints let you control which response formats a route accepts, which matters if your application serves both HTML pages and a JSON API from similar-looking URLs:

resources :articles, constraints: { format: "json" }

Constraints are a precise tool. They do not replace good route ordering, but they help you express rules about what a valid request should look like directly in your routing table, rather than pushing that logic down into the controller.

Redirects and Custom Routes

Not every route needs to point at a controller action. Sometimes you just need to redirect one URL to another, which Rails makes simple with the redirect method.

get "/old-articles", to: redirect("/articles")

For everything else, Rails gives you direct access to each HTTP verb as its own routing method: get, post, patch, put, and delete. You reach for these when a request does not fit neatly into the standard RESTful actions that resources generates for you.

get "about", to: "pages#about"
post "newsletter/subscribe", to: "newsletter#subscribe"

There is also match, which lets you respond to more than one verb for the same path, though it is used far less often than the individual verb methods, since being explicit about which verb a route responds to usually makes your intentions clearer.

match "search", to: "search#index", via: [:get, :post]

Custom routes are appropriate when an action genuinely does not map to one of the seven standard REST actions. Reaching for resources first and only adding custom routes when you actually need them keeps your routing table predictable and easy for other developers, including future you, to read.

Shallow Routing

Nested routes are great for expressing relationships, but they can produce long, unwieldy URLs once you nest more than one resource deep. Shallow routing solves this by keeping the nested prefix only for the collection actions, index, new, and create, while flattening member actions like show, edit, update, and destroy down to the top level.

Here is the before, using full nesting:

resources :articles do
  resources :comments
end

This produces /articles/5/comments/12/edit, which is longer than it needs to be, since you do not actually need the article ID to identify a specific comment once you already know its own ID.

Here is the after, using shallow: true:

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

Now the index and create routes stay nested, /articles/5/comments, but the show, edit, update, and destroy routes drop the article prefix entirely, becoming /comments/12 and /comments/12/edit. This gives you the clarity of nested routes where it matters, showing which article a new comment belongs to, while keeping individual comment URLs short and simple once the comment already has its own unique ID.

Inspecting Routes

Rails gives you a built-in command to see every route your application currently defines, which is one of the most useful debugging tools you have when something is not matching the way you expect.

bin/rails routes

Running that in your terminal prints out every route, its HTTP verb, its URL pattern, and the controller action it maps to. On a larger application, that output can get long, so Rails lets you filter it.

To see only routes related to a specific resource, you can grep by controller:

bin/rails routes -g users

This filters the output down to routes whose name, path, or controller mentions "users," which is much faster than scrolling through the entire routing table looking for what you need.

When a route is not matching the way you expect, bin/rails routes is almost always the first place to look. It tells you exactly what Rails thinks your routes are, which is often different from what you assumed you wrote, especially once route order and nesting start to interact in ways that are easy to overlook.

Common Routing Mistakes

Even experienced developers run into routing issues from time to time. Here are the ones that come up most often, and how to fix them.

Route order problems. As covered earlier, Rails matches routes top to bottom and stops at the first match. A general route defined above a specific one will silently intercept requests meant for the specific route. Fix this by placing more specific routes higher in the file.

Over-nesting resources. Nesting more than one level deep produces long, fragile URLs and awkward controller code. Fix this by nesting only one level and reaching for shallow routing when you need deeper relationships.

Using custom routes instead of REST. It is tempting to add a custom route for every new feature, but this quickly makes your routing table inconsistent and harder to predict. Fix this by defaulting to resources and only adding member or collection routes when an action genuinely does not fit the standard seven.

Duplicate routes. Defining the same path twice, sometimes across different parts of a large routes.rb file, means only the first one will ever actually run. Fix this by running bin/rails routes periodically and watching for repeated paths.

Missing route helpers. Hardcoding an ID directly, like /articles/5, instead of using article_path(@article), works until the URL structure changes, at which point every hardcoded string breaks. Fix this by always using generated route helpers instead of raw strings.

Hardcoding URLs. Similar to missing route helpers, hardcoding full URLs anywhere in your application, including in emails or JavaScript, makes your application fragile to change. Fix this by using _url helpers in contexts outside the current request, and _path helpers everywhere else.

Best Practices

A few habits will keep your routing table clean and easy to maintain as your application grows.

Prefer RESTful routes over custom ones whenever an action fits one of the standard seven. Keep URLs predictable, so that anyone familiar with REST conventions can guess what a URL does without reading your code. Limit nested resources to one level, reaching for shallow routing rather than deeper nesting. Use named route helpers everywhere instead of hardcoded strings. Organize related controllers with namespaces, especially for things like admin areas or versioned APIs. And keep routes.rb clean by grouping related routes together and removing routes that are no longer used.

Real-World Example

Let's put everything together by sketching out the routing structure for a small blog application with users, articles, categories, comments, authentication, and an admin dashboard.

Rails.application.routes.draw do
  root "articles#index"

  resources :articles, shallow: true do
    resources :comments, only: [:create, :destroy]
  end

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

  resource :session, only: [:new, :create, :destroy]
  resources :users, only: [:new, :create]

  namespace :admin do
    resources :articles
    resources :users
    resources :categories
  end
end

Walking through this: the root route sends visitors to the articles index when they land on the homepage. Articles use shallow: true so that comments, nested underneath, keep short URLs once they have their own ID. Categories only expose index and show, since categories in this application are managed through the admin dashboard rather than by regular users. Authentication uses a singular resource :session, since a user only ever has one active session, alongside a users resource limited to new and create, covering sign up. Finally, the entire admin experience lives under the admin namespace, completely separated from the public-facing controllers.

A request to create a new comment on article 5, POST /articles/5/comments, flows through the router, matches the nested comments#create route, and lands in CommentsController#create, where it looks up the parent article using params[:article_id] before saving. From there, it is the controller's job to safely process the incoming data, which is exactly where concepts like strong parameters come in. If you want to go deeper on how Rails controllers securely handle incoming form data once a route hands off a request, our guide on understanding strong parameters in Rails picks up right where this article leaves off.

If you would like to see this entire kind of structure built from scratch, step by step, our guide on building a blog with Ruby on Rails 8 walks through a complete project that puts these routing patterns to work in a real application.

Frequently Asked Questions

What is Rails routing? Rails routing is the system that maps incoming HTTP requests, identified by an HTTP verb and a URL path, to a specific controller action. It is defined in config/routes.rb and runs before any controller code executes.

What is the difference between resource and resources? resources is used for collections, where a record needs an ID to be identified, like articles. resource, singular, is used when there is only ever one instance of something in a given context, like a user's own profile, and it does not include an index action or an ID in its URLs.

What are RESTful routes? RESTful routes are the standard set of seven routes, index, new, create, show, edit, update, and destroy, generated automatically by resources. They follow the REST design philosophy of mapping common actions to predictable combinations of HTTP verbs and URLs.

What are route helpers? Route helpers are automatically generated methods, like articles_path or article_path(@article), that return the URL for a given route. Using them instead of hardcoded strings keeps your application resilient to URL changes.

How do nested routes work? Nested routes express a parent-child relationship in the URL, such as /articles/5/comments, by declaring one resources block inside another. Rails recommends nesting only one level deep to keep URLs manageable.

Why is my route not matching? The most common causes are route order, where a more general route defined earlier in the file intercepts the request, or a typo in the path or controller action name. Running bin/rails routes will show you exactly what Rails has registered.

How do I debug routes? Run bin/rails routes to see every route in your application, or bin/rails routes -g followed by a keyword to filter the output down to routes related to a specific resource or controller.

When should I use custom routes? Use custom routes, through member, collection, or direct verb methods like get and post, when an action genuinely does not fit one of the seven standard RESTful actions, such as publishing an article or running a search.

Conclusion

Routing is the front door of every Rails application, and understanding it well makes everything downstream easier to build and reason about. Once you are comfortable with resources, route helpers, nesting, namespaces, and the debugging tools Rails gives you, routing stops being a source of confusing errors and becomes one of the most predictable parts of the framework.

The best way to build that comfort is to practice. Start with a simple resources declaration, run bin/rails routes to see exactly what it generated, and then gradually add nesting, member and collection routes, and namespaces as your application's needs grow. The more routing structures you build by hand, the more natural reading and writing routes.rb files will become.