Often we observe a lot of “young” developers stucked when approaching the REST “protocol”. This article aims to show it in simple way, of course referring to RubyOnRails framework.
The REST approach (it’s not properly a “protocol”) is based on the following: usage of the well note HTTP protocols “verbs” in order to expose resources on the web.
Practically, we want to offer some (basic) actions on resources, like:
- resource reading
- new resource creation
- existant resource modification
- existant resource deletion
First question.
Thus we’are talking about creation, reading, editing and deleting it’s obvious to ask: how do we can identify resources?
It’s simple: throught an URL.
Example:
http://www.example.com/posts
http://www.example.com/posts/1
http://www.example.com/posts/my_first_post
Second question.
After a resource is identified, what operations can we do on it?
The HTTP methods (verbs) most noticed are GET and POST, but others exists. And these can be used to realize the above mentioned basic operations:
- GET: to read a resource (maybe more tha one…)
- POST: to create a new (instance of a) resource
- PUT: to modify an existant (instance of a) resource
- DELETE: to delete an existant (instance of a) resource
Thus, through the couple (method, URL) we have some API (more or less “standard”) to manipulate “resources” (CRUD: Create, Read, Update, Delete).
In Rails we can use a resource simply inserting the following statement in config/rourtes.rb file (notice that we use a controller named Posts):
ActionController::Routing::Routes.draw do |map|
map.resources :posts
end
That statement declares (implicitly) the routes for a “post” resource.
Take a look how these methods can be used (with URL) and how they are “translated” by Rails in actions (of Posts controllers):
operation | HTTP verb | action |
Create | POST /posts | create |
Read | GET /posts/1 | show |
Update | PUT /posts/1 | update |
Delete | DELETE /posts/1 | destroy |
But in “real life” we need also some action that enable a human user to “modify” and “create” a resource, thus an HTML form. For this reason the implicit routes contain also some other actions, that enrich the previous table:
operation | HTTP verb | action |
Create | POST /posts | create |
Read | GET /posts/1 | show |
Update | PUT /posts/1 | update |
Delete | DELETE /posts/1 | destroy |
(show all instances of the resource) | GET /posts | index |
show the form for a new resource instance | GET /posts/new | new |
show the form for an existing resource | GET /posts/1/edit | edit |
The thing worth to note is the fact that we are managing “resources” and not “actions”. So, when modeling our problem domain we should reason in terms of “object” rather than “verbs” (eg: “session” and not “user log-in”).
Obviously, no one can forbid use to add other actions to the controller that provides the REST “behaviour”, it’s important to not broke the previous actions.
Finally, two points interesting to note:
- we can read “all” instances of a resource throught GET /posts
- in Rails, when properly used, RESTful controllers can respond to different format (HTML, XML, JSON, etc). Using the “default” XML format give us a sort of auto-descriptive XML fragment for each resource.
23.10.2008 at 15:08
A nice introduction that point to the main REST points! Keep on ;-)