Photo credit: http://flickr.com/photos/drdul/

UPDATE April 18, 2007: I fixed the URL convention for the "new" action to /airports/new instead of /airports/1;new which was incorrect. It's only the edit action that uses the semicolon in Rails 1.2.

Last time we learned that a REST design starts by identifying a few key resources. Today we need to talk about how Rails will route all of the REST-compliant requests, and how it expects you to handle those requests.

I want also take a step back for a moment, and mention that REST is not a Rails-only thing. REST was developed long before Rails, and is simply an approach that can be applied to many kinds of software applications. For example, now that I know about REST, I'll probably never write another WinForms app the same way again.

Resource == Controller

You already know about models and controllers. But how do you coordinate them to implement your newly-found RESTful design? First, let's get a few things out of the way:

• A resource is not always a one-to-one mapping to a Rails model or database table. Sometimes a resource is "virtual" and exists in your domain vocabulary and application logic, but is not backed by a database table.
• However, a resource is always mapped to a Rails controller.
• For you abstract-interface lovers out there (like me), you can consider your controller class to be the "concrete implementation" of your REST interface.
• Your controller will implement your resource regardless of which kind of client is talking to it (html browser, xml client, feed aggregator, etc.) As such, it will need to be able to respond accordingly, and send its responses and return values back to the client in the format that the client expects (html, xml, etc.) Back in part 3, I said we wanted different kinds of clients (web, cell phone, rich client, etc.) to be able to access the same resources. A single controller is responsible for rendering its resource, regardless of which client is making the request.

Seven

Most resources want to be accessible individually (an airport) an as a collection (the list of all airports). Your controller will have these seven actions (methods):

These four:

• show : this handles a GET request for the representation of one resource instance.
• create : this handles a POST request for creating a new resource instance.
• update : this handles a PUT request for updating an existing resource.
• destroy : this handles a DELETE request on a resource instance.

plus these three:

• index : this handles a GET request for a representation of the collection.
• new : this handles a GET request for a blank form useful for creating a new resource. Usually makes sense only for HTML clients.
• edit : this handles a GET request for a form that is pre-filled with current values of an existing resource. Again, usually only for HTML clients.

The names of these methods are important, because the Rails routing infrastructure will be expecting them.

Of course, you can choose to implement fewer if you want. If your business rules say that a certain resource should only be rendered as read-only, then you might only need to implement the index and show methods, for example.

You may already be wondering how in the world you're going to develop a Rails application if those are the only actions you're allowed to have in your controllers. Well, first of all, don't worry. If you really, really think you have a situation that requires a few extra actions, then go right ahead and add them to your controller. Just remember that having any extra actions can be a warning sign that you haven't identified all of your resources yet.

The Traffic Cop

We need to connect some dots now. How do we map the URLs and HTTP verbs into method calls on our controller?

Normally, the action to be called in your controller is obvious just by looking at the url. I hope you remember how Rails normally translates incoming HTTP requests into calling methods in your controller code. If you don't remember, here's a five-second refresher course: your routes.rb file specifies how to translate URLs into controller classes and methods:

map.connect '/airports/:action/:id', :controller => 'airports'

This example maps a url like www.mydomain.comm/airports/open/45 to a controller class named AirportsController and a method named open. While the open method is running, params[:id] will yield 45.

But to implement REST with the Rails framework, things would need to be done differently. First of all, we will want the same url to sometimes map to different actions, depending on which HTTP verb has come along for the ride. In other words, this URL:

/airports/1

should map to our show action (for airport #1) if the HTTP verb was GET, but it should map to our destroy action if the HTTP verb was DELETE.

Prior to Rails 1.2, there wasn't a way to specify all that logic in the map.connect statement. Fortunately, 1.2 introduced a small but extremely important enhancement to the routing vocabulary. It's so cool, in fact, that unless you are aware of REST, you might have absolutely no idea how great this little enhancement really is to the Rails framework:

map.resources 'airports'

This code is short but it says a lot. It tells Rails all of these things:

• you have resources called airports (note the plural form, that's important)
• you want Rails to follow RESTful conventions and map incoming requests accordingly
• routing will not be based on URL pattern alone, but URL pattern paired with an HTTP verb
• it should route all requests to this resource through a controller named AirportsController (note, plural again)
• all URLs for this resource will follow a very specific convention (I'll describe those below)
• you want a set of pre-defined named routes for each action for this resource

The URL/verb pairs Rails will now automatically map for you look like this:

• /airports/ + POST = create
• /airports/1 + GET = show
• /airports/1 + PUT = update
• /airports/1 + DELETE = destroy
• /airports/ + GET = index
• /airports/new + GET = new

• /airports/1;edit + GET = edit

  NOTE: That strange-looking semicolons are correct for Rails 1.2.3, but they will be changed to forward-slashes in Rails 2.0

Now all you have to do is implement the seven methods in your controller, and Rails handles the rest!

Don't Order Yet

But wait, there's more. There's a really neat generator that comes with Rails 1.2 and later called scaffold_resource, that will give a complete RESTful skeleton for your resource: it will add the routing code, a simple but functional controller implementing all seven methods, a migration for the underlying table, and RHTML templates for all of them! It's a great way to get started.

In fact, the best thing you can do to learn about REST is to start a fresh rails app and generate a resource. Create a database called myapp_development and myapp_test (for example), and then do this:

c:\dev> rails myapp
c:\dev> cd myapp
c:\dev\myapp> ruby script/generate scaffold_resource airport name:string designator:string
c:\dev\myapp> rake db:migrate

Start up ruby script/server and go to localhost:3000/airports. You'll be able to create new airports, edit them, and delete them! How does it work?

Just open up airport_controller.rb - it's all right there. The Ruby code will be amazingly short. Study the code. It's very important that you understand the controller code before we move on.

Then, look at each of the .rhtml templates that were generated for you, and look for the use of named routes. Get a feel for how an incoming request gets routed to a controller action and which .rhtml will get rendered back to the client.

Now, there's probably one construct in the controller code that you haven't seen before: the strange-looking respond_to block. That's an important pillar of of our entire RESTful implementation, and we'll go into more details about it next time.