By: Myles Eftos

February 29th, 2008

Reader Rating: 9

As you may have read in my blog post, RESTful Rails Part I [1], RESTful Rails is a way of mapping HTTP verbs (GET, POST, PUT, and DELETE) to CRUD actions (Create, Read, Update, and Delete) in your Rails apps. If that sentence was complete gibberish to you, take some time to read the blog post and it may make a bit more sense.

Alright, I assume you've had enough to time to absorb my post, and you're full of CRUD and REST. Now, it's time to build an actual example.

REST Tumblelog

For this example, we'll build a (very) basic tumblelog-type app. What's a Tumblelog? Well it's like a blog but without the essays. A Tumblelog is a jumble of frequent but short posts that are typically just a link, a quote, a quick comment, and so on.

To start, you'll need to create a new rails project called rest_tumble, with one model and one controller. So fire up you favourite console and run:

rails rest_tumble  
cd rest_tumble  
script/generate model post  
script/generate controller posts

Open up db/migrate/001_create_posts.rb and edit it to look like this:

class CreatePosts
 def up      
   create_table do |t|
     t.string :message, :null => false, :limit => 140        
     t.timestamps      
   end    
 end    
 def self.down      
   drop_table :posts    
 end  
end

Then, run:

rake db:migrate

Finally, add some validation to the post model (app/models/post.rb):

class Post < ActiveRecord::Base
 validates_presence_of :message    
 validates_length_of :message, :maximum => 140  
end

Okay, so that now we've created the Rails app, let's configure the controller and the routes. If you cast your mind back to the last article, you would remember that there are four different RESTful verbs. Let's add those four methods to our controller (app/controllers/posts_controller.rb):

class PostsController < ApplicationController    
 # GET - displays all posts    
 def index    
 end    
 
 # GET - shows one post (based on the supplied id)    
 def show    
 end    
 
 # POST - creates a new post    
 def create    
 end    
 
 # PUT - updates an existing post    
 def update    
 end    
 
 # DELETE - deletes a post    
 def destroy    
 end  
end

You can see from the comments above how each REST verb maps to the controller methods. You'll also notice that even though there are four verbs, we need five methods. The GET verb has two corresponding methods: one shows all the posts, while the other shows a specific post. We actually need two more methods -- new and edit -- to complete the controller.

We add these extra methods for two reasons. First of all, Rails uses the same endpoint (plus maybe an id) for all the verbs, so if we link to /posts (a GET method), Rails will return a list of posts. By adding these methods, we have a way to display the forms.

Let's add the extra methods and some code:

class PostsController < ApplicationController    
 # GET - displays all posts    
 def index      
   @posts = Post.find :all, :order => 'created_at ASC'    
 end    
 
 # GET - shows one post (based on the supplied id)    
 def show      
   @post = Post.find(params[:id])    
 end    
 
 # GET - displays a form which can be used to create a post
 def new  
   @post = Post.new    
 end    
 
 # POST - create a new post    
 def create      
   @post = Post.new(params[:post])      
   @post.save!      
   redirect_to post_path(@post)    
   rescue ActiveRecord::RecordInvalid      
   render :action => 'new'    
 end    
 
 # GET - displays a form allowing us to edit an existing post
 def edit
   @post = Post.find(params[:id])
 end    
 
 # PUT - update an existing post    
 def update      
   @post = Post.find(params[:id])      
   @post.attributes = params[:post]      
   @post.save!      
   redirect_to post_path(@post)    
   rescue ActiveRecord::RecordInvalid      
   render :action => 'edit'    
 end    
 
 # DELETE - delete a post    
 def destroy      
   @post  = Post.find(params[:id])      
   @post.destroy      
   redirect_to posts_path    
 end  
end

If you've ever done any Rails coding before, there won't be any surprises here, with the possible exception of the posts_path, post_path, edit_post_path, and delete_post_path methods. These special methods will generate a path to a resource based on entries in routes.rb. If you can't remember the syntax (and it can get a little tricky with things like nested routes), you can run the ever-helpful routes rake task, like so:

rake routes

But for those special methods to work, we need to tell Rails that we have a REST resource. Open up config/routes.rb and add the following line (about halfway through the code, you should see a similar example line that has been commented out; put this line under it):

  map.resources :posts

All this does is tell Rails that we have a posts_controller that wants to be RESTful, so it needs to respond accordingly. Try out the routes rake task to see the results of your handiwork.

To complete the site, we need to add the views -- each GET action needs a corresponding view: index.html.erb, show.html.erb, new.html.erb, and edit.html.erb. I've also created a _form.html.erb partial, because the form code for the new and edit methods is basically the same.

Here's the index view. There's nothing too special about this file -- again, we use post_path, this time as a parameter of the link_to tag:

# app/views/posts/index.html.erb  
<%= link_to 'New message', new_post_path %>  
<hr />  
<% if @posts.empty? -%>    
 <p>There are no posts</p>  
<% else -%>    
 <% @posts.each do |post| -%>      
   <p>        
     <%= link_to h(post.message), post_path(post) -%>      
   </p>    
 <% end -%>  
<% end -%>

Here's is the show view. For this page, we show a delete button and edit link:

# show.html.erb  
<p><%= h(@post.message) -%></p>  
 
<% form_tag post_path(@post), :method => :delete do -%>    
 <%= link_to 'Edit', edit_post_path(@post) -%>    
 <button type="submit">Delete</button>  
<% end -%>

You'll notice in the above code that we have a call to a form_tag incorporating a post_path and a delete method. This instructs the form to perform a DELETE action when the button's pressed. However, when the edit link is clicked, we get taken to the special edit view.

Both the new and edit views are basically the same -- so much so that we use a partial for the common code:

# app/views/posts/new.html.erb  
<%= error_messages_for('post') %>  
 
<% form_tag posts_path do -%>    
 <%= render :partial => 'posts/form' %>    
 
 <fieldset>      
   <button type="submit">Save</button>      
   <%= link_to 'Cancel', posts_path %>    
 </fieldset>  
<% end -%>  
 
# app/views/posts/edit.html.erb  
<%= error_messages_for('post') %>  
 
<% form_tag post_path(@post), :method => :put do -%>    
 <%= render :partial => 'posts/form' %>    
 
 <fieldset>      
   <button type="submit">Update</button>      
   <%= link_to 'Cancel', posts_path %>    
 </fieldset>  
<% end -%>

You'll notice that, once again, we set a method attribute, this time with PUT. We don't need to do this for the new view, as the default action for a form, POST, is right for our new action.

Finally, let's look at the form partial, which is all very run-of-the-mill as far as Rails forms go:

# app/views/posts/_form.html.erb  
<fieldset>    
 <legend>Enter your message</legend>    
 
 <label for="post_message">Message</label>    
 <%= text_area 'post', 'message' %>  
</fieldset>

Let's run it and see what happens! Run:

ruby script/server

And pointing your browser to http://localhost:3000/posts. With any luck, you should see something similar to this:

Congratulations! You just created a RESTful Rails app!

XML Goodness

Now, I'll be the first to admit that this demo isn't really that impressive -- we could have done exactly the same thing using regular CRUD Rails. But where RESTful Rails becomes awesome is when you're able to publish your own web services for free (well, almost for free -- we need to add a couple of lines of code, but that's it).

To do this, we need to tell Rails that it should respond differently to an XML request. Thankfully, the respond_to method does all the heavy lifting for us. So let's modify the post's controller to look like this:

class PostsController < ApplicationController    
 # GET - displays all posts    
 def index      
   @posts = Post.find :all, :order => 'created_at ASC'      
   respond_to do |format|        
     format.xml { render :xml => @posts.to_xml }        
     format.html { }      
   end    
 end      
 
 # GET - shows one post (based on the supplied id)    
 def show      
   @post = Post.find(params[:id])      
   respond_to do |format|        
     format.xml { render :xml => @post.to_xml }        
     format.html { }      
   end    
 end      
 
 # GET - displays a form which can be used to create a post    
 def new      
   @post = Post.new    
 end      
 
 # POST - create a new post    
 def create      
   @post = Post.new(params[:post])      
   @post.save!        
 
   respond_to do |format|        
     format.html { redirect_to post_path(@post) }        
     format.xml { render :xml => @post.to_xml,  
       :status => :created }      
   end    
   rescue ActiveRecord::RecordInvalid      
   respond_to do |format|        
     format.html { render :action => 'new' }        
     format.xml { render :xml => @post.errors.to_xml,  
       :status => 500 }      
   end    
 end      
 
 # GET - displays a form allowing us to edit an existing post    
 def edit      
   @post = Post.find(params[:id])    
 end      
 
 # PUT - update an existing post    
 def update      
   @post = Post.find(params[:id])      
   @post.attributes = params[:post]      
   @post.save!        
 
   respond_to do |format|        
     format.html { redirect_to post_path(@post) }        
     format.xml { render :xml => @post.to_xml,  
       :status => :ok }      
   end    
   rescue ActiveRecord::RecordInvalid      
   respond_to do |format|        
     format.html { render :action => 'edit' }        
     format.xml { render :xml => @post.errors.to_xml,  
       :status => 500 }      
   end    
 end      
 
 # DELETE - delete a post    
 def destroy      
   @post  = Post.find(params[:id])      
   @post.destroy      
   respond_to do |format|        
     format.html { redirect_to posts_path }        
     format.xml { head :ok }      
   end    
 end  
end

Let's take a look at what we've done here. We've introduced the new respond_to block, which allows us to separate the xml and html requests. We've also introduced to the app different types of rendering, using the built-in XML type, as well as utilizing to_xml to convert objects to serialized XML for output. Finally, this example shows us how to output different HTTP status codes.

The index and show methods are very simple: if the request is XML, it serializes the object (or objects) and spits them down the line. If you've installed curl [2], you can test this very easily. First, add a couple of posts using the web interface, then type the following in to a terminal:

curl -H 'Accept: application/xml' http://localhost:3000/posts.xml

This command should return a list of posts that you've made.

The next features -- creating, updating and deleting -- are the most interesting. If you tell Rails that the content you're posting is XML, it will automagically convert (or at least try to convert) the data into an array from which we can create an object.

On completion of a successful Tumblelog post, we send an HTTP status code of 201 Created, accompanied by a copy of the new post object. Sending the new object in the response means the consumer of the web service doesn't have to make another query to find it, which gives them a handy reference point.

The curl command would look something like this:

curl -H 'Accept: application/xml' -H 'Content-type: application/xml' http://localhost:3000/posts.xml -d '<post><message>A RESTful message</message></post>' -X POST

When we're successfully updating an existing post, we return a regular status code of 200 OK, again with a copy of the object. For example, if we had an object with an id of 4, we could update it with this code:

curl -H 'Accept: application/xml' -H 'Content-type: application/xml' http://localhost:3000/posts/4.xml -d '<post><message>An updated RESTful message</message></post>' -X PUT

In both the examples above, if the submitted data is not complete, Rails will return the error messages as XML with a status code 500 Internal Server Error.

The final example is a delete, which simply returns a 200 OK response:

curl -H 'Accept: application/xml' -H 'Content-type: application/xml' http://localhost:3000/posts/4.xml -X DELETE

Exercises For You at Home

You may have noticed that the error handling for the XML version of the site is fairly basic. If you try to update a post that doesn't exist, you'll get a HTML error. Try to work out a way to do this with XML -- and do the same with other exceptions. Here's a clue: look at the rescue_from class method.

See if you can work out how to generate a JSON version of the site that would be suitable for responding to AJAX requests. Once you start, you'll find it easier than you think!

Tying Up Some Loose Ends

1. These instructions are run against Rails 2.0.2 using the default SQLite3 database, which is why we don't need to configure MySQL.


2. I'm aware that Rails offers a resource generator that will automatically generate a model, controller, and set of templates for your RESTful app, but you wouldn't learn anything if I used that, would you?


3. As I mentioned in my previous post, no browsers can perform HTTP PUT or DELETE requests. Rails emulates them by injecting a secret hidden input field, named _method. Try it out and view source on the edit page. You'll see the form's method is still a trusty old POST, and there's an extra input field.


4. I hate the fact that there's no default delete special method, to allow you to add a deletion confirmation view. I usually add it using the :member attribute in the routes file (config/routes.rb), so our previous addition to this file would become:

   map.resources :posts, :member => { :delete => :get }
   
   This allows me to add a delete view (delete.html.erb) as well as letting me replace the delete form and button with a link in the show view (show.html.erb).

Conclusion

That completes the very basic example of a RESTful Rails site. Obviously, there is some other stuff you would need to add for a working web site (authentication for one), but what we have achieved is still pretty impressive. As promised you can download the complete source code for your own use [3].

[1] http://www.sitepoint.com/blogs/2008/02/04/restful-rails-part-i/
[2] http://en.wikipedia.org/wiki/CURL
[3] http://www.sitepoint.com/blogs/wp-content/uploads/2008/02/rest_tumble.tgz