Programming

RESTful Rails. Part I

    Myles Eftos
    Share

    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…