CRUD through HTTP is a good step forward to using resources and becoming RESTful, another step further into it is to make use of hypermedia based services and this gem allows you to do it really fast.

Example on accessing a resource and its services through the restfulie API:

order = Order.from_web resource_uri

puts "Order price is #{order.price}"

order.pay payment                        # sends a post request to pay this order

order.cancel                             # sends a delete request

This is a simple example how to make your state changes available to your resource consumers:

	class Order < ActiveRecord::Base
	  def following_states
	    states = [ {:controller => :orders, :action => :show } ]
	    states << {:controller => :orders, :action => :destroy} if can_cancel?
	    states << {:controller => :orders, :action => :pay, :id => id} if can_pay?
	    states << {:controller => :payments, :action => :show, :payment_id => payment.id } if paied?
	    states
	  end

Installing

Just add in your environment.rb the following line:

config.gem "restfulie", :source => "http://gemcutter.org"

And then execute:

rake gems:install

or, if you prefer to install it as a plugin:

script/plugin install git://github.com/caelum/restfulie.git

Typical Restful Example

Trying to follow the definition of a RESTful application supporting resources with hypermedia content, a resource would be:

<order>
	<product>basic rails course</product>
	<product>RESTful training</product>
	<atom:link rel="refresh" href="http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom"/>
	<atom:link rel="update" href="http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom"/>
	<atom:link rel="pay" href="http://www.caelum.com.br/orders/1/pay" xmlns:atom="http://www.w3.org/2005/Atom"/>
	<atom:link rel="destroy" href="http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom"/>
</order>

Client Usage

One should first acquire the representation from the server through your common GET request and process it through the usual from_* methods:

xml = Net::HTTP.get(URI.parse(‘http://www.caelum.com.br/orders/1’))

order = Order.from_xml(xml)

or use the restfulie from_web:

order = Order.from_web ‘http://www.caelum.com.br/orders/1’

And now you can invoke all those actions in order to change your resource’s state:

order.refresh
order.update
order.destroy
order.pay

Note that:

• refresh is get
• update is put (and you have to put everything back)
• destroy is delete
• pay (unknown methods) is post

Resource format support

Restfulie currently supports full xml+atom, partial xml+rel and will soon expand its support to json+links.

Help

If you are looking for or want to help, let us know at the mailing list:

http://groups.google.com/group/restfulie

Client-side configuration: how to customize your request

HTTP verbs

By default, restfulie uses the following table:

• destroy, cancel and delete send a DELETE request
• update sends a PUT request
• refresh, reload, show, latest sends a GET request
• other methods sends a POST request

If you want to use a custom http verb in order to send your request, you can do it by setting the optional string ‘method’:

order.update(:method=>"post")

Request parameters

If you want to send extra parameters, you can do it through the data parameter:

order.pay(:data => {:payment => my_payment})

The parameters will be serialized either to xml or json according to which format was used to deserialize the order at first place.

Executing another GET request

If your method executes another GET request, it will automatically deserialize its result as:

order = Order.from_web order_uri
payment = order.check_payment_info

If you want to parse the response yourself, instead of receiving just the final deserialized object, you can do it by passing a body to your method

order = Order.from_web order_uri
successful = order.check_payment_info do |response|
  return response.code==200
end

Server-side configuration

Using xml+rel links instead of atom links

Atom is everywhere and can be consumed by a number of existing tools but if your system wants to supply its
services through commons rel+link xml as

	<order>
		<product>basic rails course</product>
		<product>RESTful training</product>
		<refresh>http://www.caelum.com.br/orders/1</refresh>
		<update>http://www.caelum.com.br/orders/1</update>
		<pay>http://www.caelum.com.br/orders/1/pay</pay>
		<destroy>http://www.caelum.com.br/orders/1</destroy>
	</order>

You can do it by passing the use_name_based_link argument:

    order.to_xml(:controller => my_controller, :use_name_based_link => true)

Team

Restfulie was created and is maintained within Caelum by

Commiters

• Caue Guerra
• Guilherme Silveira

Collaborators

• Diego Carrion

Try it online

We have a live example of a server implementation using a resource+hypermedia course ordering system available.

Follow the steps below to try out the system:

• Access the server system
• Create a couple of trainings
• Create an order
• Access the order listing and retrieve its xml link

And now you can try the restfulie client api through a simple and generic resource+hypermedia client application:

• Access the client system
• Enter your order uri
• Check your order information which was retrieved and all available actions

Now you can either:

• latest – refresh your order information order.latest
• cancel – cancel your order (dead end!) order.destroy
• pay – pay for your order, and don’t forget to send your (fake) credit card information order.pay(payment)
• check_payment_info – after paying you can check the payment information stored at the server order.checkpayment_info_

In order to pay do not forget to send the parameter payment with a value as

 <payment>
   <amount>15</amount>
   <cardholder_name>Guilherme Silveira</cardholder_name>
   <card_number>123456789012</card_number>
   <expiry_month>12</expiry_month>
   <expiry_year>12</expiry_year>
 </payment>

Sources

Client
Server

License

/*

• Copyright © 2009 Caelum – www.caelum.com.br/opensource
• All rights reserved.
  *
• Licensed under the Apache License, Version 2.0 (the “License”);
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at
  *
• http://www.apache.org/licenses/LICENSE-2.0
  *
• Unless required by applicable law or agreed to in writing, software
• distributed under the License is distributed on an “AS IS” BASIS,
• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
• See the License for the specific language governing permissions and
• limitations under the License.
  */