The Rails 4 Way (2014)

Chapter 3. REST, Resources, and Rails

Before REST came I (and pretty much everyone else) never really knew where to put stuff.

—Jonas Nicklas on the Ruby on Rails mailing list

With version 1.2, Rails introduced support for designing APIs consistent with the REST style. Representational State Transfer (REST) is a complex topic in information theory, and a full exploration of it is well beyond the scope of this chapter.⁸ We’ll touch on some of the keystone concepts, however. And in any case, the REST facilities in Rails can prove useful to you even if you’re not a REST expert or devotee.

The main reason is that one of the inherent problems that all web developers face is deciding how to name and organize the resources and actions of their application. The most common actions of all database-backed applications happen to fit well into the REST paradigm.

3.1 REST in a Rather Small Nutshell

REST is described by its creator, Roy T. Fielding, as a network architectural style, specifically the style manifested in the architecture of the World Wide Web. Indeed, Fielding is not only the creator of REST but also one of the authors of the HTTP protocol itself. REST and the web have a very close relationship.

Fielding defines REST as a series of constraints imposed upon the interaction between system components. Basically, you start with the general proposition of machines that can talk to each other, and you start ruling some practices in and others out by imposing constraints that include (among others):

· Use of a client-server architecture

· Stateless communication

· Explicit signaling of response cacheability

· Use of HTTP request methods such as GET, POST, PUT and DELETE

The World Wide Web allows for REST-compliant communication. It also allows for violations of REST principles; the constraints aren’t always all there unless you put them there. As for this chapter, the most important thing you have to understand is that REST is designed to help you provide services using the native idioms and constructs of HTTP. You’ll find, if you look for it, lots of discussion comparing REST to, for example, SOAP—the thrust of the pro-REST argument being that HTTP already enables you to provide services, so you don’t need a semantic layer on top of it. Just use what HTTP already gives you.

One of the allures of REST is that it scales relatively well for big systems, like the web. Another is that it encourages—mandates, even—the use of stable, long-lived identifiers (URIs). Machines talk to each other by sending requests and responses labeled with these identifiers. Messages consist of representations (manifestations in text, XML, graphic format, and so on) of resources (high-level, conceptual descriptions of content) or simply HTTP headers.

Ideally at least, when you ask a machine for a JSON representation of a resource—say, Romeo and Juliet—you’ll use the same identifier every time and the same request metadata indicating that you want JSON, and you’ll get the same response. And if it’s not the same response, there’s a reason—like, the resource you’re retrieving is a changeable one (“The current transcript for Student #3994,” for example).

3.2 Resources and Representations

The REST style characterizes communication between system components (where a component is, say, a web browser or a server) as a series of requests to which the responses are representations of resources.

A resource, in this context, is a “conceptual mapping” (Fielding). Resources themselves are not tied to a database, a model, or a controller. Examples of resources include

· The current time of day

· A library book’s borrowing history

· The entire text of The Little Prince

· A map of Jacksonville Beach

· The inventory of a store

A resource may be singular or plural, changeable (like the time of day) or fixed (like the text of The Little Prince). It’s basically a high-level description of the thing you’re trying to get hold of when you submit a request.

What you actually do get hold of is never the resource itself, but a representation of it. This is where REST unfolds onto the myriad content types and actual deliverables that are the stuff of the web. A resource may, at any given point, be available in any number of representations (including zero). Thus your site might offer a text version of The Little Prince, but also an audio version. Those two versions would be understood as the same resource, and would be retrieved via the same identifier (URI). The difference in content type—one representation vs. another—would be negotiated separately in the request.

3.3 REST in Rails

The REST support in Rails consists of methods to define resources in the routing system, designed to impose a particular style and order and logic on your controllers and, consequently, on the way the world sees your application. There’s more to it than just a set of naming conventions (though there’s that too). In the large scheme of things, the benefits that accrue to you when you use Rails’ REST support fall into two categories:

· Convenience and automatic best practices for you

· A RESTful interface to your application’s services for everyone else

You can reap the first benefit even if you’re not concerned with the second. In fact, that’s going to be our focus here: what the REST support in Rails can do for you in the realm of making your code nicer and your life as a Rails developer easier.

I don’t mean to minimize the importance of REST itself, nor the seriousness of the endeavor of providing REST-based services. Rather, it’s an expedient; we can’t talk about everything, and this section of the book is primarily about routing and how to do it, so we’re going to favor looking at REST in Rails from that perspective.

Getting back to practical matters, the focus of the rest of this chapter will be showing you how REST support works in Rails opening the door to further study and practice including the study of Fielding’s dissertation and the theoretical tenets of REST. We won’t cover everything here, but what we do cover will be onward compatible with the wider topic.

The story of REST and Rails starts with CRUD…

3.4 Routing and CRUD

The acronym CRUD (Create Read Update Delete) is the classic summary of the spectrum of database operations. It’s also a kind of rallying cry for Rails practitioners. Because we address our databases through abstractions, we’re prone to forget how simple it all is. This manifests itself mainly in excessively creative names for controller actions. There’s a temptation to call your actions add_item and replace_email_address and things like that. But we needn’t, and usually shouldn’t, do this. True, the controller does not map to the database, the way the model does. But things get simpler when you name your actions after CRUD operations, or as close to the names of those operations as you can get.

The routing system does not force you to implement your app’s CRUD functionality in any consistent manner. You can create a route that maps to any action, whatever the action’s name. Choosing CRUD names is a matter of discipline. Except… when you use the REST facilities offered by Rails, it happens automatically.

REST in Rails involves standardization of action names. In fact, the heart of the Rails’ REST support is a technique for creating bundles of named routes automatically—named routes that are bundled together to point to a specific, predetermined set of actions.

Here’s the logic. It’s good to give CRUD-based names to your actions. It’s convenient and elegant to use named routes. The REST support in Rails gives you named routes that point to CRUD-based action names. Therefore, using the REST facilities gives you a shortcut to some best practices.

Shortcut hardly describes how little work you have to do to get a big payoff. If you put

resources :auctions

into your config/routes.rb file, you will have created four named routes, which, in a manner to be described in this chapter, connect to seven controller actions. And those actions have nice CRUD-like names, as you will see.

3.4.1 REST Resources and Rails

Like most of Rails, support for RESTful applications is “opinionated”; that is, it offers a particular way of designing a REST interface, and the more you play along, the more convenience you reap from it. Most Rails applications are database-backed, and the Rails take on REST tends to associate a resource very closely with an Active Record model, or a model/controller stack.

In fact, you’ll hear people using the terminology fairly loosely. For instance, they’ll say that they have created a Book resource. What they mean, in most cases, is that they have created a Book model, a book controller with a set of CRUD actions, and some named routes pertaining to that controller (courtesy of resources :books). You can have a Book model and controller, but what you actually present to the world as your resources, in the REST sense, exists at a higher level of abstraction: The Little Prince, borrowing history, and so on.

The best way to get a handle on the REST support in Rails is by going from the known to the unknown. In this case, from the topic of named routes to the more specialized topic of REST.

3.4.2 From Named Routes to REST Support

When we first looked at named routes, we saw examples where we consolidated things into a route name. By creating a route like

get 'auctions/:id' => "auction#show", as: 'auction'

you gain the ability to use nice helper methods in situations like

link_to item.description, auction_path(item.auction)

The route ensures that a path will be generated that will trigger the show action of the auctions controller. The attraction of this kind of named route is that it’s concise and readable.

Now, think in terms of CRUD. The named route auction_path is a nice fit for a show (the R in CRUD) action. What if we wanted similarly nicely named routes for the create, update, and delete actions?

Well, we’ve used up the route name auction_path on the show action. We could make up names like auction_delete_path and auction_create_path but those are cumbersome. We really want to be able to make a call to auction_path and have it mean different things, depending on which action we want the URL to point to.

We could differentiate between the singular (auction_path) and the plural (auctions_path). A singular URL makes sense, semantically, when you’re doing something with a single, existing auction object. If you’re doing something with auctions in general, the plural makes more sense.

The kinds of things you do with auctions in general include creating. The create action will normally occur in a form:

form_tag auctions_path

It’s plural because we’re not saying “perform an action with respect to a particular auction”, but rather “with respect to the collection of auctions, perform the action of creation.” Yes, we’re creating one auction, not many. But at the time we make the call to our named route, auctions_path, we’re addressing auctions in general.

Another case where you might want a plural named route is when you want an overview of all of the objects of a particular kind, or at least, some kind of general view, rather than a display of a particular object. This kind of general view is usually handled with an index action. These indexactions typically load a lot of data into one or more variables, and the corresponding view displays it as a list or table (possibly more than one).

Here again, we’d like to be able to say:

link_to "Click here to view all auctions", auctions_path

Already, though, the strategy of breaking auction_path out into singular and plural has hit the wall: We’ve got two places where we want to use the plural named route. One is create; the other is index. But they’re both going to look like

/auctions

How is the routing system going to know that when we use auctions_path as a link versus using it in a form that we mean the create action and not index? We need another qualifier, another flag, another variable on which to branch.

Luckily, we’ve got one.

3.4.3 Reenter the HTTP Verb

Form submissions are POSTs by default. Index actions are GETs. That means that we need to get the routing system to realize that

/auctions submitted in a GET request!

versus

/auctions submitted in a POST request!

are two different things. We also have to get the routing system to generate the same URL—/auctions—but with a different HTTP request method, depending on the circumstances.

This is what the REST facility of Rails routing does for you. It allows you to stipulate that you want /auctions routed differently, depending on the HTTP request method. It lets you define named routes with the same name, but with intelligence about their HTTP verbs. In short, it uses HTTP verbs to provide that extra data slot necessary to achieve everything you want to achieve in a concise way.

The way you do this is by using a special routing method: resources. Here’s what it would look like for auctions:

resources :auctions

That’s it. Making this one call inside routes.rb is the equivalent of defining four named routes. And if you mix and match those four named routes with a variety of HTTP request methods, you end up with seven useful—very useful—permutations.

3.5 The Standard RESTful Controller Actions

Calling resources :auctions involves striking a kind of deal with the routing system. The system hands you four named routes. Between them, these four routes point to seven controller actions, depending on HTTP request method. In return, you agree to use very specific names for your controller actions: index, create, show, update, destroy, new, edit.

It’s not a bad bargain, since a lot of work is done for you and the action names you have to use are nicely CRUD-like.

Table 3.1 summarizes what happens. It’s a kind of “multiplication table” showing you what you get when you cross a given RESTful named route with a given HTTP request method. Each box (the nonempty ones, that is) shows you, first, the URL that the route generates and, second, the action that gets called when the route is recognized. (The table lists _path methods rather than _url ones, but you get both.)

Table 3.1: RESTful Routes Table Showing Helpers, Paths, and the Resulting Controller Action

(The edit and new actions have unique named routes, and their URLs have a special syntax.)

Since named routes are now being crossed with HTTP request methods, you’ll need to know how to specify the request method when you generate a URL, so that your GET’d clients_url and your POST’d clients_url don’t trigger the same controller action. Most of what you have to do in this regard can be summed up in a few rules:

1. The default request method is GET.

2. In a form_tag or form_for call, the POST method will be used automatically.

3. When you need to (which is going to be mostly with PATCH and DELETE operations), you can specify a request method along with the URL generated by the named route.

An example of needing to specify a DELETE operation is a situation when you want to trigger a destroy action with a link:

link_to "Delete", auction_path(auction), method: :delete

Depending on the helper method you’re using (as in the case of form_for), you might have to put the method inside a nested hash:

form_for "auction", url: auction_path(auction),

html: { method: :patch } do |f|

That last example, which combined the singular named route with the PATCH method, will result in a call to the update action when submitting the form (as per row 2, column 4 of Table 3.1). You don’t normally have to program this functionality specifically, because as we’ll see later in the book, Rails automatically figures out whether you need a POST or PATCH if you pass an object to form helpers.

3.5.1 PATCH vs. PUT

If you are coming from a previous version of Rails, you may be wondering why the update action of a RESTful route is mapped to the HTTP verb PATCH instead of PUT. In the HTTP standards document RFC 5789, it outlines that a PUT request to a given resource is meant to completely replace it on the origin server. However, when updating a resource in Rails, rarely, if ever, do you replace an entire resource when performing an update. For example, when updating an Active Record model, Rails sets the attribute updated_at timestamp, not the requesting client.

To follow better HTTP semantics, Rails will be using the HTTP verb PATCH for updates. PATCH allows for both full and partial updates of a resource, and is more suited to how Rails updates resources.

If you are upgrading an existing Rails application, the HTTP verb PUT will still map to the update action in RESTful routes, but it’s recommended to use PATCH moving forward.

3.5.2 Singular and Plural RESTful Routes

As you may have noticed, some of the RESTful routes are singular; some are plural. The logic is as follows:

1. The routes for show, new, edit, and destroy are singular, because they’re working on a particular resource.

2. The rest of the routes are plural. They deal with collections of related resources.

The singular RESTful routes require an argument, because they need to be able to figure out the id of the member of the collection referenced.

item_url(item) # show, update, or destroy, depending on HTTP verb

You don’t have to call the id method on item. Rails will figure it out (by calling to_param on the object passed to it.)

3.5.3 The Special Pairs: new/create and edit/update

As Table 3.1 shows, new and edit obey somewhat special RESTful naming conventions. The reason for this has to do with create and update, and how new and edit relate to them.

Typically, create and update operations involve submitting a form. That means that they really involve two actions—two requests—each:

1. The action that results in the display of the form

2. The action that processes the form input when the form is submitted

The way this plays out with RESTful routing is that the create action is closely associated with a preliminary new action, and update is associated with edit. These two actions, new and edit, are really assistant actions: All they’re supposed to do is show the user a form, as part of the process of creating or updating a resource.

Fitting these special two-part scenarios into the landscape of resources is a little tricky. A form for editing a resource is not, itself, really a resource. It’s more like a pre-resource. A form for creating a new resource is sort of a resource, if you assume that being new—that is, nonexistent—is something that a resource can do, and still be a resource!

That line of reasoning might be a little too philosophical to be useful. The bottom line, as implemented in RESTful Rails, is the following: The new action is understood to be giving you a new, single (as opposed to plural) resource. However, since the logical verb for this transaction is GET, and GETting a single resource is already spoken for by the show action, new needs a named route of its own.

That’s why you have to use

link_to "Create a new item", new_item_path

to get a link to the items/new action.

The edit action is understood not to be giving you a full-fledged resource, exactly, but rather a kind of edit flavor of the show resource. So it uses the same URL as show, but with a kind of modifier, in the form of /edit, hanging off the end, which is consistent with the URL form for new:

/items/5/edit

The corresponding named route is edit_item_url(@item). As with new, the named route for edit involves an extra bit of name information, to differentiate it from the implied show of the existing RESTful route for GETting a single resource.

3.5.4 The PATCH and DELETE Cheat

We have just seen how Rails routes PATCH and DELETE requests. Some HTTP clients are able to use said verbs, but forms in web browsers can’t be submitted using anything other than a POST. Rails provides a hack that is nothing to worry about, other than being aware of what’s going on.

A PATCH or DELETE request originating in a browser, in the context of REST in Rails, is actually a POST request with a hidden field called _method set to either "patch" or "delete". The Rails application processing the request will pick up on this, and route the request appropriately to theupdate or destroy action.

You might say, then, that the REST support in Rails is ahead of its time. REST components using HTTP should understand all of the request methods. They don’t, so Rails forces the issue. As a developer trying to get the hang of how the named routes map to action names, you don’t have to worry about this little cheat. And hopefully some day it won’t be necessary any more.

3.5.5 Limiting Routes Generated

It’s possible to add :except and :only options to the call to resources in order to limit the routes generated.

resources :clients, except: [:index]

resources :clients, only: [:new, :create]

3.6 Singular Resource Routes

In addition to resources, there’s also a singular (or singleton) form of resource routing: resource. It’s used to represent a resource that only exists once in its given context.

A singleton resource route at the top level of your routes can be appropriate when there’s only one resource of its type for the whole application, perhaps something like a per-user profile.

resource :profile

You get almost the full complement of resource routes, all except the collection route (index). Note that the method name resource, the argument to that method, and all the named routes generated are in the singular.

$ rake routes

profile POST /profile(.:format) profiles#create

new_profile GET /profile/new(.:format) profiles#new

edit_profile GET /profile/edit(.:format) profiles#edit

GET /profile(.:format) profiles#show

PATCH /profile(.:format) profiles#update

PUT /profile(.:format) profiles#update

DELETE /profile(.:format) profiles#destroy

It’s assumed that you’re in a context where it’s meaningful to speak of the profile—the one and only—because there’s a user to which the profile is scoped. The scoping itself is not automatic; you have to authenticate the user and retrieve the profile from (and/or save it to) the database explicitly. There’s no real magic or mind-reading here; it’s just an additional routing technique at your disposal if you need it.

3.7 Nested Resources

Let’s say you want to perform operations on bids: create, edit, and so forth. You know that every bid is associated with a particular auction. That means that whenever you do anything to a bid, you’re really doing something to an auction/bid pair—or, to look at it another way, an auction/bid nest. Bids are at the bottom of a drill-down hierarchical structure that always passes through an auction.

What you’re aiming for here is a URL that looks like

/auctions/3/bids/5

What it does depends on the HTTP verb it comes with, of course. But the semantics of the URL itself are: the resource that can be identified as bid 5, belonging to auction 3.

Why not just go for bids/5 and skip the auction? For a couple of reasons. First, the URL is more informative—longer, it’s true, but longer in the service of telling you something about the resource. Second, thanks to the way RESTful routes are engineered in Rails, this kind of URL gives you immediate access to the auction id, via params[:auction_id].

To created nested resource routes, put this in routes.rb:

1 resources :auctions do

2 resources :bids

3 end

What that tells the routing mapper is that you want RESTful routes for auction resources; that is, you want auctions_url, edit_auction_url, and all the rest of it. You also want RESTful routes for bids: auction_bids_url, new_auction_bid_url, and so forth.

However, the nested resource command also involves you in making a promise. You’re promising that whenever you use the bid named route helpers, you will provide a auction resource in which they can be nested. In your application code, that translates into an argument to the named route method:

link_to "See all bids", auction_bids_path(auction)

When you make that call, you enable the routing system to add the /auctions/3 part before the /bids part. And, on the receiving end—in this case, in the action bids/index, which is where that URL points—you’ll find the id of auction in params[:auction_id]. (It’s a plural RESTful route, using GET. See Table 3.1 again if you forgot.)

You can nest to any depth. Each level of nesting adds one to the number of arguments you have to supply to the nested routes. This means that for the singular routes (show, edit, destroy), you need at least two arguments:

link_to "Delete this bid", auction_bid_path(auction, bid), method: :delete

This will enable the routing system to get the information it needs (essentially auction.id and bid.id) in order to generate the route.

Alternatively, instead of specifying the route to be used in a view helper, such as link_to, you can simply pass an object.

link_to "Delete this bid", [auction, bid], method: :delete

Since the object in the above example is an Array, Rails infers that the route is nested. And, based on the order and class names of the objects in the Array, Rails will use the auction_bid_path helper behind the scenes.

3.7.1 RESTful Controller Mappings

Something we haven’t yet explicitly discussed is how RESTful routes are mapped to a given controller. It was just presented as something that happens automatically, which in fact it does, based on the name of the resource.

Going back to our recurring example, given the following nested route:

1 resources :auctions do

2 resources :bids

3 end

there are two controllers that come into play, the AuctionsController and the BidsController.

3.7.2 Considerations

Is nesting worth it? For single routes, a nested route usually doesn’t tell you anything you wouldn’t be able to figure out anyway. After all, a bid belongs to an auction.

That means you can access bid.auction_id just as easily as you can params[:auction_id], assuming you have a bid object already.

Furthermore, the bid object doesn’t depend on the nesting. You’ll get params[:id] set to 5, and you can dig that record out of the database directly. You don’t need to know what auction it belongs to.

Bid.find(params[:id])

A common rationale for judicious use of nested resources, and the one most often issued by David, is the ease with which you can enforce permissions and context-based constraints. Typically, a nested resource should only be accessible in the context of its parent resource, and it’s really easy to enforce that in your code based on the way that you load the nested resource using the parent’s Active Record association.

auction = Auction.find(params[:auction_id])

bid = auction.bids.find(params[:id]) # prevents auction/bid mismatch

If you want to add a bid to an auction, your nested resource URL would be

http://localhost:3000/auctions/5/bids/new

The auction is identified in the URL rather than having to clutter your new bid form data with hidden fields or resorting to non-RESTful practices.

3.7.3 Deep Nesting?

Jamis Buck is a very influential figure in the Rails community, almost as much as David himself. In February 2007, via his blog, he basically told us that deep nesting was a bad thing, and proposed the following rule of thumb: Resources should never be nested more than one level deep.

That advice is based on experience and concerns about practicality. The helper methods for routes nested more than two levels deep become long and unwieldy. It’s easy to make mistakes with them and hard to figure out what’s wrong when they don’t work as expected.

Assume that in our application example, bids have multiple comments. We could nest comments under bids in the routing like this:

1 resources :auctions do

2 resources :bids do

3 resources :comments

4 end

5 end

Instead, Jamis would have us do the following:

1 resources :auctions do

2 resources :bids

3 end

4

5 resources :bids do

6 resources :comments

7 end

8

9 resources :comments

Notice that each resource (except auctions) is defined twice, once in the top-level namespace, and one in its context. The rationale? When it comes to parent-child scope, you really only need two levels to work with. The resulting URLs are shorter and the helper methods are easier to work with.

auctions_path # /auctions

auctions_path(1) # /auctions/1

auction_bids_path(1) # /auctions/1/bids

bid_path(2) # /bids/2

bid_comments_path(3) # /bids/3/comments

comment_path(4) # /comments/4

I personally don’t follow Jamis’ guideline all the time in my projects, but I have noticed something about limiting the depth of your nested resources, it helps with the maintainability of your codebase in the long run.

3.7.4 Shallow Routes

As of Rails 2.3, resource routes accept a :shallow option that helps to shorten URLs where possible. The goal is to leave off parent collection URL segments where they are not needed. The end result is that the only nested routes generated are for the :index, :create, and :new actions. The rest are kept in their own shallow URL context.

It’s easier to illustrate than to explain, so let’s define a nested set of resources and set :shallow to true:

1 resources :auctions, shallow: true do

2 resources :bids do

3 resources :comments

4 end

5 end

alternatively coded as follows (if you’re block-happy)

1 resources :auctions do

2 shallow do

3 resources :bids do

4 resources :comments

5 end

6 end

7 end

The resulting routes are:

bid_comments GET /bids/:bid_id/comments(.:format)

POST /bids/:bid_id/comments(.:format)

new_bid_comment GET /bids/:bid_id/comments/new(.:format)

edit_comment GET /comments/:id/edit(.:format)

comment GET /comments/:id(.:format)

PATCH /comments/:id(.:format)

PUT /comments/:id(.:format)

DELETE /comments/:id(.:format)

auction_bids GET /auctions/:auction_id/bids(.:format)

POST /auctions/:auction_id/bids(.:format)

new_auction_bid GET /auctions/:auction_id/bids/new(.:format)

edit_bid GET /bids/:id/edit(.:format)

bid GET /bids/:id(.:format)

PATCH /bids/:id(.:format)

PUT /bids/:id(.:format)

DELETE /bids/:id(.:format)

auctions GET /auctions(.:format)

POST /auctions(.:format)

new_auction GET /auctions/new(.:format)

edit_auction GET /auctions/:id/edit(.:format)

auction GET /auctions/:id(.:format)

PATCH /auctions/:id(.:format)

PUT /auctions/:id(.:format)

DELETE /auctions/:id(.:format)

If you analyze the routes generated carefully, you’ll notice that the nested parts of the URL are only included when they are needed to determine what data to display.

3.8 Routing Concerns

One of the fundamental principles Rails developers follow is Don’t Repeat Yourself (DRY). Even though this is the case, the config/routes.rb file can be prone to having repetition in the form of nested routes that are shared across multiple resources. For example, let’s assume in our recurring example, that both auctions and bids can have comments associated with them.

1 resources :auctions do

2 resources :bids

3 resources :comments

4 resources :image_attachments, only: :index

5 end

6

7 resources :bids do

8 resources :comments

9 end

To eliminate some code duplication and to encapsulate shared behavior across routes, Rails 4 introduces the routing method concern.

1 concern :commentable do

2 resources :comments

3 end

4

5 concern :image_attachable do

6 resources :image_attachments, only: :index

7 end

To add a routing concern to a RESTful route, pass the concern to the :concerns option.

1 resources :auctions, concerns: [:commentable, :image_attachable] do

2 resources :bids

3 end

4

5 resources :bids, concerns: :commentable

The :concerns option can accept one or more routing concerns.

3.9 RESTful Route Customizations

Rails’ RESTful routes give you a pretty nice package of named routes, mapped to useful, common, controller actions—the CRUD superset you’ve already learned about. Sometimes, however, you want to customize things a little more, while still taking advantage of the RESTful route naming conventions and the multiplication table approach to mixing named routes and HTTP request methods.

The techniques for doing this are useful when, for example, you’ve got more than one way of viewing a resource that might be described as showing. You can’t (or shouldn’t) use the show action itself for more than one such view. Instead, you need to think in terms of different perspectives on a resource, and create URLs for each one.

3.9.1 Extra Member Routes

For example, let’s say we want to make it possible to retract a bid. The basic nested route for bids looks like this:

1 resources :auctions do

2 resources :bids

3 end

We’d like to have a retract action that shows a form (and perhaps does some screening for retractability). The retract isn’t the same as destroy; it’s more like a portal to destroy. It’s similar to edit, which serves as a form portal to update. Following the parallel with edit/update, we want a URL that looks like

/auctions/3/bids/5/retract

and a helper method called retract_auction_bid_url. The way you achieve this is by specifying an extra member route for the bids, as in Listing 3.1

Listing 3.1: Adding an extra member route