Overview

Enables default REST functionality, more than what you get with Rails out-of-the-box, to keep your code DRY. This means you can write code like this:

class Posts < ApplicationController
  include Rest 
end

Which would automatically add the following REST actions to your controller:

  • index

  • show

  • new

  • edit

  • create

  • update

  • destroy

How is that for being DRY? Read on to learn more.

License

Copyright © 2008-2009 Brooke Kuhlmann of Berserk Technologies. See the included LICENSE for more info.

History

See the CHANGELOG file for more info.

Requirements

  1. Knowledge of Representational State Transfer (REST).

  2. Ruby on Rails (automatically installed for you if you don’t have 2.3.x or higher).

  3. mislav-will_paginate gem (automatically installed for you).

Installation

Type the following from the command line to install:

  • UNIX: sudo gem install aeonscope-rest

  • Windows: gem install aeonscope-rest

Update your environment.rb file to include the new gem:

  • config.gem “aeonscope-rest”, :lib => “rest”, :source => “gems.github.com”

Then run the following generator to complete setup (TIP: suffix the command line with -h option for usage):

  • script/generate rest_setup

Usage

As mentioned in the overview, simply add the following line of code to your controller(s) to make them RESTful:

include Rest

Example:

class Posts < ApplicationController
  include Rest 
end

This will automatically create the seven REST actions (index, show, new, create, edit, update, and destroy) for your controller. The model (i.e. Post) and model instance (i.e. @posts or @post depending on the action) are automatically determined from the controller name. Just make sure your routes are updated to reflect the new resource. For example:

map.resources :posts

This means you can immediately write the following code in your views:

index.html.erb

<h2>Posts</h2>
<div>
  <table>

<thead> <tr> <th>Label</th> <th>Created At</th> <th>Updated At</th> <th>Actions</th> </tr> </thead> <tbody> <%= render @posts %> </tbody>

  </table>
</div>

show.html.erb

<h2>Label</h2>
<p><%= @post.label %></p>

<h2>Content</h2>
<p><%= @post.content %></p>

<p><%= link_to "Back", :back %></p>

new_or_edit.html.erb

 <% form_for @post do |form| %>
   <%= form.error_messages :header_data => :strong, :header_message => "Error" %>

   <div>
     <%= form.label :label %><br/>
     <%= form.text_field :label %>
   </div>

   <div>
     <%= form.label :content %><br/>
     <%= form.text_area :content %>
   </div>

   <div><%= submit_tag "Save", :class => "form-button" %> or <%= link_to "Cancel", posts_path %></div>
<% end %>

Notice how the form_for helper method automatically determines what controller action to use based off the model object (i.e. @post). This allows you to use the same form for new and edit actions by creating one template called: new_or_edit.html.erb. Nice, eh?

To customize the RESTful behavior of your controller, use any combination of these three macros:

  • belongs_to - Enables resource nesting where a controller can belong to a parent controller. This behavior is similar to the ActiveRecord belongs_to macro.

  • resource_options - Allows you to customize the default behavior of your controller(s). There is a lot you can do with this, read the code documentation for more info.

  • disabled_actions - Allows you to disable any of the default REST actions. Follow the link to learn more.

Example:

class Comments < ApplicationController
  include Rest
  belongs_to :posts
  resource_options :label => "My Wicked Comments"
  disabled_actions :show, :destroy
end

Here is the breakdown, line-by-line, of the example shown above:

  1. Enables restful behavior.

  2. Identifies the comments controller as a child of the posts controller (i.e. nested resource).

  3. Instead of using the default label “Comments”, a customized label of “My Wicked Comments” is used instead.

  4. The “show” and “destroy” actions are disabled which means only the following actions will work: index, new, edit, create, and update.

Using the post and comment controller relationship as defined above, we can break this relationship down even further. The post (parent) resource would have the following values (in this case, all default values):

  • parent_key = N/A

  • parent_value = N/A

  • parent_resource_method = N/A

  • controller_class = PostsController

  • controller_name = “posts”

  • label = “Posts”

  • model_class = Post

  • model_name = post

  • model_object = @post #<Post id: 1, label: “Test”, content: “Test”, created_at: “2008-10-31 23:59:28”, updated_at: “2008-10-31 23:59:28”>

  • namespaces = []

  • index_template = “/posts/index”

  • show_template = “/posts/show”

  • new_or_edit_template = “/posts/new_or_edit”

The comment (child) resource would have the following values:

  • parent_key = post_id

  • parent_value = 1

  • parent_resource_method = N/A

  • controller_class = CommentsController

  • controller_name = “comments”

  • label = “My Wicked Comments”

  • model_class = Comment

  • model_name = comment

  • model_object = @comment #<Comment id: 1, post_id: 1, label: “Test”, content: “Test”, created_at: “2008-10-31 23:59:28”, updated_at: “2008-10-31 23:59:28”>

  • namespaces = []

  • index_template = “/comments/index”

  • show_template = “/comments/show”

  • new_or_edit_template = “/comments/new_or_edit”

Resources

To learn more about REST in Rails, check out the following:

  • RESTful Rails - A PDF work downloading and reading that inspired me to write this gem.

  • Rails Routing - The definitive guide to RESTful routing in Rails.

  • Taking Things Too Far - A good read on knowing when you have gone too far with REST API.

Contact/Feedback/Issues