REST in simple words

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.