Photo credit: http://www.flickr.com/photos/pantagrapher/

Last time, we learned how Rails conventions enables your HTML to access your resources. But we want our software to support more than just HTML clients. Our flight schedule software needs to be accessible by web browsers, cell phones, and even third-party libraries.

As far as REST concepts are concerned, we've covered the basics in parts 1 through 4. If this was a dot-to-dot picture, we've already placed our dots. Now we can connect them and see what we've been making! This is actually one of my favorite parts about REST in Rails, because it's another example of the beautiful Ruby language underneath.

Short But Oh So Sweet

To connect our dots, we have to make our Rails controllers provide different responses depending on who's on the other end of the line. Let's take an easy example: getting a list of airports. If you used the scaffold_resource generator in Rails 1.2, you got code that looked something like this:

    class AirportsController < ApplicationController

        def index
            @airports = Airport.find :all

            respond_to do |format|
                format.html  # do nothing, allow Rails to render index.rhtml
                format.js    # do nothing, allow Rails to render index.rjs
                format.xml   { render :xml => @airports.to_xml }
            end
        end

    end

The first line is easy: find all the airports. The rest of it is some weird-looking code. But that's all there is, and it's able to render the list of airports in HTML, XML, and even with some ajax when needed! So once you understand the respond_to stuff, you'll be all set.

In HTTP, client applications provide meta-information about their request in the HTTP "header". The header is just a bunch of optional key-value pairs that the client can send along. There are some predefined key names that can be used. One of the standard keys is the "Accept-Type". The client can pass along an "Accept-Type" value to indicate what kind of format the client can "accept," or understand. If it's omitted, the server assumes that the client can understand HTML. But any valid MIME type can be specified. If the client sends "Accept-Type: text/xml", then the server is supposed to respond with an XML document fragment instead of HTML markup.

So, it's this Accept-Type header that enables all of the magic inside the respond_to block. Let's imagine implementing this the lame way. Pretend that Rails could pass the value of the Accept-Type value to your action method, so you could render the correct response:

    class AirportsController < ApplicationController

        # Pretend that Rails will call our index action, 
            # and will pass in the value of the Accept-Type header
        def index(client_format)
            @airports = Airport.find :all

            if client_format == "text/html"
                # TO DO: render the default template

            elsif client_format == "application/javascript"
                # TO DO: return some javascript

            elsif client_format == "application/xml" || client_format == "text/xml"
                # TO DO: return some XML back the client

            # ... more elsif statements here for each MIME type you want to support
            end
        end

    end

Clean Up Time

You have to squint past the ugliness, but the code is pretty simple: based on the requested format, we return the correct representation of our list of airports. I imagine the core team might have started with code that was something like this (or at least in their head even if they didn't type it), and they quickly refactored by added a helper method called respond_to. Let's look at the respond_to snippet again:

  respond_to do |format|
    format.html  # do nothing, allow Rails to render index.rhtml
    format.js    # do nothing, allow Rails to render index.rjs
    format.xml   { render :xml => @airports.to_xml }
  end

First, while we might not know much about the weird respond_to method, we do know one thing - it takes a Ruby block. (If you don't know about Ruby blocks, well, go do some Googling first and then come back.) Inside the block, you get passed a rather odd-behaving variable I've called format. And then it looks like we're calling three methods on the format object.

Here's the idea: Rails can't magically know which types of clients you want to support, but it can already do 80% of the work for you. You just need to somehow indicate which kinds of clients you want to accept, and for each client, you need to render a representation of your resource that can be understood by that particular client. So instead of Rails telling you which format was requested, it expects you to tell it which formats you are able to "respond to" (get it?). And for each format, you (optionally) provide a block of your own, that is able to provide the representation for that format.

In the example above, we're telling Rails that for HTML and Javascript clients, Rails can do its default behavior - find the right template and render it, but if a client wants XML, then we supply a block with the actual implementation.

Remember, a long time ago, in a galaxy far, far away, we talked about the difference between a resource and its many possible representations? How HTML is really just one representation of a resource? ("Your application is not a web page", etc.?) Now you can even see that in our code: html is just one of the possible ways we render our resources. Awesome, huh?

Parting Advice

Naturally, we can't cover everything there is to know about REST. That's why we called it "101". But we have talked about how to design your application in a "restful" way and how it's different from traditional object-oriented design. We've talked about the concept of resources, and how they are your paradigm for your application.

Wondering what to do next? Try it! Just create a Rails app from scratch, try the scaffold_resource generator, study the code, and then try to customize the views. Try to customize the controllers. It's easier than you think.

Here are some resources I recommend (note, PeepCode supports this blog):

• The PeepCode episode on REST
• DHH's keynote from RailsConf 2006 and blog entry
• Keep up with what's new in Rails with Ryan Daigle

Got others? Link 'em up in the comments.