Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Ruby
Branch: master

This branch is 1 commit ahead, 1806 commits behind caelum:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
README.textile
Rakefile
init.rb

README.textile

Quit pretending

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

Restfulie: client-side

Here you can see how to access a resource and its services through the restfulie API:

order = Order.from_web resource_uri      # retrieves order resource (xml/atom/json support)

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

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

order.cancel                             # sends a delete request

Restfulie: server-side

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"

Execute:

rake gems:install

or, if you prefer to install 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 typical restful 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" 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 process 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)

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

order.refresh
order.update
order.destroy
order.pay(payment)

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 xml+atom and will soon expand its support to xml+rel links and json+links supports. Those new formats will also support automatic http verb detection – if possible and reasonable.

Help

If you are looking for or want to help, let us know at the mailing list: http://groups.google.com/group/restfulie

How to customize your request

By default, restfulie uses the following table:

  • destroy, cancel and delete send a DELETE request
  • update sends a POST request
  • refresh, reload, show 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")

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.
    */
Something went wrong with that request. Please try again.