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
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.
http://www.example.com/posts http://www.example.com/posts/1 http://www.example.com/posts/my_first_post
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):
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:
|(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.