But You Said You Were Done

Last time, we concluded our REST 101 series.

Or so we thought.

We developed those articles when 1.2 was a mature, stable release, and when it had also become clear that 2.0 would not significantly change what had already been achieved in 1.2.

However, Rails 2.0 did fine-tune the way we develop RESTful applications in Rails, prompting us to add one more article and bring the series up to date.

REST Refresher

Let’s review what we covered in the first five articles:

1. When deciding what controllers you need, think in terms of resources.
2. Don’t think twice about what actions your controllers should have. Use the Golden Seven for each resource: index, new, edit, create, show, update, delete.
3. A resource maps to Rails controller, not necessarily to an underlying model.
4. Deliver your resources in a way that’s appropriate to the user’s experience. Some users want HTML, some want RSS, some want audio, some have big screens, some have tiny cell phone screens, some want to use your application like a web service and expect XML to be returned.
5. The client application will indicate their preference with the “Accept” header in the http request. Use respond_to in your controller to automatically map the Accept header to your response.

Once you’ve identified a resource that you want to implement, you just need to implement it RESTfully in Rails.

The Hard Way

I can’t believe I’m saying that anything in Rails is actually hard, but if there is a “hard” way to write RESTful code, this would be it (“by hand” is more precise, I suppose). Here’s the recipe:

1. If your resource needs a supporting model, use script/generate model <resource-name> (or ruby script\generate model on Windows). You can now specify any columns you already know your model needs right on the command line, which will give you a nice head start in your migration file.

Don’t forget to rake db:migrate before you start running your tests (you thought I was going to say “running your app”, didn’t you?)

script/generate model Airport city:string identifier:string

2. Generate a nice empty controller with script/generate controller <resource-name> and fill it with the standard seven actions.

script/generate controller Airports

Using textmate? You can steal our Textmate snippet to quickly write all the boilerplate code for you.

3. Create views only for the actions that need them, typically these are:

• index.html.erb
• new.html.erb
• edit.html.erb
• update.html.erb
• show.html.erb

In Rails 2.0, the middle part of the template filename maps to the HTTP mime type (more or less), so you might also have files named index.iphone.erb or show.xml.builder.

Also, be sure to learn the cool new form_for syntax in Rails 2.0 that automatically generates the right target url based on whether you give it a new object (which will target the create action) or one that’s already been saved to the database (which will target the update action).

In fact for a nice overview of all that’s new in Rails 2.0, we recommend the PeepCode Rails 2.0 PDF by Ryan Daigle (disclaimer: PeepCode supports this blog.) Ryan’s blog is also an excellent way to keep up on all the new stuff in Rails.

4. Add a map.resources line to your routing file. There are lots of options here, but the simplest looks like:

map.resources :airports

This will generate a package of handy named routes, map incoming action/verb pairs to the right controller action, and automatically ensure that actions like create, update and delete only respond to POST verbs only.

But you knew all this already – it’s been around since Rails 1.2.

5. Always, always, always try to use named routes whenever you use link_to and any other helper method that expects a hash of url options. The syntax of named paths has changed somewhat in 2.0 to make it easier to construct links for the most typical scenarios. Check the Rails API docs and use the new rake routes task as a cheat sheet whenever you need it.

Help Rails Help You

Ok, now for what’s new in Rails 2.0 that can make this process much easier.

Rails 2.0 has two built-in generators to make your RESTful life easier.

1. Generating A Resource Without Views

If you have a model underpinning your resource, you can get 80% of the way done by using the totally awesome resource generator (again, available since Rails 1.2, but somehow few people know about it). It’s syntax is identical to the model generator, but it will also create a RESTful controller with the Golden Seven actions and add a map.resources line for you.

script/generate resource Airport city:string identifier:string

So what was the other 20%? The views are not generated for you.

2. Generating Everything With The Scaffold Generator

You can inch up to 95% of the way for the simplest situations by using the new scaffold generator.

Ok, time out.

We’ve always said that the scaffold generator was bad. Very bad.

So now we’re recommending it?

Not if you’re using 1.2.x or earlier. In that case, do not use the scaffold generator. If you’re using 1.2, you can use the scaffold_resource generator instead.

But in Rails 2.0, the scaffold generator is no longer evil, it is downright righteous. It will create the model, controller, routes, and view scaffolding that demonstrates how to use the new form_for syntax. Very cool stuff. Again, it uses the model generator syntax, so use the singular form of your resource and specify any columns you already know up front:

script/generate scaffold Airport city:string identifier:string

You’ll end up rewriting the views to truly fit your application, but that’s the whole idea. It’s scaffolding, not the real thing, silly.

If you’ve used the resource generator and now want the scaffolded views as well, you’re in luck: Brian Hogan has released a gem to do just that for you.

(Oh, and I know we had you at “easier.”)

Ok, NOW we’re done

We hope this wraps up our REST series. At least for now.

Questions? Comments? Applause? Complaints? Bring it on in the comments.