RESTful Rails. Part I

RESTful Rails have been a a much debated part of the Rails core, since the original restful_rails plugin was merged in to core just over a year ago. But with the improvements that have been made in Rails 2.0, they are here to stay, so it is important to understand what they are, how they work and when to (and when NOT to) use them. This is actually a pretty big topic, and I think it is worth while giving you some background first, so I’ll split the post in twain – Part I is theoretical, Part II is practical. So get your network protocol hats on, and get ready to learn about the inner workings of the language of the web.

REST vs. CRUD

Where would the web be with out acronyms? REST stands for REpresentational State Transfer and describes resources (in our case URLs) on which we can perform actions. CRUD, which stands for Create, Read, Update, Delete, are the actions that we perform. Although, in Rails, REST and CRUD are bestest buddies, the two can work fine on their own. In fact, every time you have written a backend system that allows you to add, edit and delete items from the database, and a frontend that allows you to view those items, you have been working with CRUD.

HTTP Verbs

Any web developer who has had to deal with form data would be aware of the GET and POST methods. The former will submit data back to the server via a query string that looks something like this ?key2=value2&key2=value2 and the latter sends the data via HTTP headers. What you might not realise is that every time you are load a page (that isn’t a form of type POST) you are making a GET request. So when you clicked the link in your RSS reader that bought you here, you made a GET request.

There are two other verbs that you might not have heard of because browsers don’t support them: PUT and DELETE. The delete action is obvious – if instructs the server to delete something. The PUT instruction is a little bit more cryptic – it is the same as POST action from the point of view that is sends data via headers, but it is designed to modify something (It also should create a new object if the object doesn’t already exist, but Rails ignores this minor technically).

The more astute of you may have noticed that GET sounds a lot like READ, POST looks like CREATE, PUT is the same as UPDATE and DELETE is DELETE. If you did, move straight to the head of the class – this is exactly the correlation that Rails uses when working with RESTful rails.

HTTP Response codes

Everyone knows that if you try to access a page that doesn’t exist, the server will throw you back 404 Page not Found, or if you mess up your rails code, you will get a 500 Application Error. These are response codes that the server sends back to let your browser know what is going on. Anything between 200-299 means the request was a success, 300-399 means the request was ok, but you need to do something else, 400-499 is an error and 500-599 is a really bad error. Just as there are verbs to match RESTful requests, there are response codes that correspond to RESTful responses.

200 OK
You will get from a GET, PUT or a DELETE request. It means that the request checked out and the appropriate action has been taken
201 Created
Notifies you that the POST command successfully created the posted object.
404 Not found
Means the request resource wasn’t found. You can get this from a GET, PUT or DELETE.
406 Not Acceptable
The verb isn’t allowed at the resources you reqested (More on this next part)
500 Internal Server Error
Something went horribly wrong

Resources

You would be used to seeing Rails URLs that look something like /posts/view/2 – which roughly translates to “Please let me view the post with the id number 2″. RESTful resources are very similar, in that they have a controller and (maybe) and id. What they generally don’t have is an action, because it is inherent in the HTTP verb.

To make this work, the Rails team have defined a number of special methods in the controllers that define resources – in this case posts (the .xml bit will become clear in the next part).

Method Resource Verb Explanation
index /posts.xml GET Returns all items
show /posts/1.xml GET Return a single item with id = 1
create /posts.xml POST Create an item
update /posts/1.xml PUT Update item with id = 1
delete /posts/1.xml DELETE Delete item with id = 1

In reality, you can define additional actions (You can’t make every web site fit this model), and I will go through these in my next post.

So, in the next part, we will look at how to create a RESTful rails project and how to wire everything up. Until then…

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Paul Annesley

    It’s probably worth noting that POST and PUT requests send their data in the body of the request – after the headers, not in them. It’ll make little or no practical difference to most users, but might trip somebody up.

  • madpilot

    Thanks for the correction, Paul. You are 100% correct.

  • tndalpaul

    There’s been considerable discussion whether POST or PUT should handle creation or update. For example see
    http://www.megginson.com/blogs/quoderat/2005/04/03/post-in-rest-create-update-or-action/

    wherein, for example, Mark Baker Says:
    > April 4th, 2005 at 10:56:16
    > FWIW, both POST and PUT can do creation; PUT > for when the client knows the URI of the
    > thing it’s trying to create, and POST for
    > when it doesn’t.

  • http://www.duskdesigns.com/ vSkyfluxx

    It might not be a bad idea to also include the “new” and “edit” actions in your resources table.

  • madpilot

    vSkyfluxx: I’m going to go through the specifics of the Rails REST implementation in my next post.

    Thanks