REST and Rails – no reason to be scared

I’ve been meaning to try simply_restul for a while now, and today’s announcement on rails-core pushed me over the edge. It’s no longer a plugin, it lost it’s name and changed a few things, but it’s pretty much the same. I’m going to do a quick tutorial on setting up a RESTful controller. It’s not hard — I was just scared of it!

rails simple

This creates a new rails project named “simple”. Without a -d flag, it will use mysql by default

cd rails

mysqladmin -u root create simple_development

mysqladmin -u root create simple_test

create our databases – if this were a longer tutorial, we’d test it as we went.

rake rails:freeze:edge

Make your project use the latest version of rails “Edge”. You have to do this if you want to follow along. In the future, this step will be unnecessary

script/generate model Person

Our example object – a Person
[source:ruby]
db/migrate/001_create_people.rb:
class CreatePeople < ActiveRecord::Migration
def self.up
create_table :people do |t|
t.column "name", :string
t.column "bio", :text
end
end

def self.down
drop_table :people
end
end
[/source]

rake db:migrate

We’re creating our table now using a migration. If everything went well, you’ll now have a table in your database – “people”, with two columns, name and bio.

Add the following line to your config/routes.rb

map.resources :people

(this is a change from simply_restful, plural now) Here is where the magic happens. This one line of code will give you a bunch of stuff. All the mappings between REST and your controller will now just work.

script/generate controller people index new create show edit update destroy

Create our controller with all the REST / rails actions.

app/controllers/people_controller.rb:
<br /> class PeopleController < ApplicationController<br /> # lots of actions need to look at the person sent in params[:id], so don't repeat yourself<br /> before_filter :find_person, :except => [:index, :new, :create]</p> <p> # maps to /people – named route of person_url<br /> # HTTP verb: GET<br /> def index<br /> @people = Person.find(:all)<br /> respond_to do |format|<br /> format.html<br /> format.xml { render :xml => @people.to_xml }<br /> end<br /> end</p> <p> # maps to /people/new – named route of new_person_url<br /> def new<br /> @person = Person.new<br /> end</p> <p> # gets called when for POSTs to /people<br /> def create<br /> @person = Person.new(params[:person])<br /> @person.save!<br /> respond_to do |format|<br /> format.html do<br /> flash[:notice] = “Person was successfuly created”<br /> redirect_to person_url(@person)<br /> end<br /> format.js<br /> end<br /> end</p> <p> # maps to /people/:id – named route of person_url(person_object)<br /> # HTTP verb: GET<br /> def show<br /> respond_to do |format|<br /> format.html<br /> format.xml { render :xml => @person.to_xml }<br /> end<br /> end</p> <p> # maps to /people/:id;edit – named route of edit_person_url(person_object)<br /> def edit<br /> end</p> <p> # gets called for PUT to /people/:id<br /> def update<br /> @person.attributes = params[:person]<br /> @person.save!<br /> respond_to do |format|<br /> format.html do<br /> flash[:notice] = “Person updated”<br /> redirect_to person_url(@person)<br /> end<br /> format.js<br /> end<br /> end</p> <p> # maps to /person/:id;destroy<br /> # HTTP verb: DELETE<br /> def destroy<br /> @person.destroy<br /> respond_to do |format|<br /> format.html do<br /> flash[:notice] = “Person destroyed”<br /> redirect_to people_url<br /> end<br /> format.xml { render :nothing => true }<br /> end<br /> end</p> <p>protected<br /> def find_person<br /> @person = Person.find(params[:id])<br /> end<br /> end<br />

Here’s a lot of code. This is the person controller and all the actions that you want to do on a person. They map to HTTP verbs very nicely. You should type the code (the generator made a lot if it for you, you just need to fill in the methods)

You’ll notice the funny “respond_to do |format|” stuff. This is one of the other slick features: you can send the client the format they want. So if someone were to request /person/1.xml – they clearly want xml output – this handles that (and so much more).

That was all fine and good. We could write a very nice test suite for all the code to now and still be lost on the views. Let’s go through them quickly.

app/views/people/index.rhtml

<br /> < % @people.each do |p| %></p> <div id="person_<%= p.id %>“></p> <p>Name:< %= link_to h(p.name), person_url(p) %></p> <p>Bio:< %= h p.bio %></p> </div> <p>< % end %><br /> < %= link_to "New Person", new_person_url %><br />

app/views/people/new.rhtml

</p> <h2>New person</h2> <p>< % form_for :person, @person, :url => person_url, :method => :post do |f| %><br /> < %= render :partial => “form”, :object => f %><br /> < % end %><br />

app/views/people/show.rhtml

</p> <h3>< %= h @person.name %></h3> <p> < %= h @person.bio %> </p> <p>< %= link_to "Edit", edit_person_url(@person) %><br />

app/views/people/edit.rhtml
</p> <h2>Edit person: < %= h @person.name ></h2> <p>< % form_for :person, @person, :url => person_url(@person), :html => { :method => ‘put’ } do |f| ><br /> < %= render :partial => ‘form’, :object => f ><br /> < % end ><br />

app/views/people/_form.rhtml
</p> <p> <label for='person_name'>Name</label><br /> < %= form.text_field :name > </p> <p> <label for='person_bio'>Bio</label><br /> < %= form.text_area :bio > </p> <p> < %= submit_tag %> </p> <p>

This concludes the whirlwind tour of the new RESTful Rails controllers.
I’ll be changing this post a lot based on feedback, so check back.