h1. Web site

Restfulie's website can be found at "http://restfulie.caelumobjects.com":http://restfulie.caelumobjects.com
From there you can see some videos and read the "Restfulie from Scratch guide":http://restfulie.caelumobjects.com/caelumobjects-restful-rails.pdf.

h1. Quit pretending

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 and semantic meaningful media types: this gem allows you to do it really fast.

You can read the "article on using the web for real":http://guilhermesilveira.wordpress.com/2009/11/03/quit-pretending-use-the-web-for-real-restfulie/ which gives an introduction to hypermedia/resources/services.

h2. Why would I use restfulie?

#  Easy --> writing hypermedia and semantic meaningful media type aware clients
#  Small -> it's not a bloated solution with a huge list of APIs
#  HATEOAS --> clients you are unaware of will not bother if you change
#  HATEOAS --> consumed resources will not affect your software whenever they change their flow
#  Adaptability --> clients are able to adapt to your changes
 
h2. Simple server example

In the server side, all you need to do is notify inherited_resources which media types you are able to represent your resource:

<pre>
	class OrdersController < ApplicationController
	  include Restfulie::Server::ActionController::Base

	  respond_to :atom, :html, :xml, :commerce, :opensearch

	  def index
	    respond_with @orders = Order.all
	  end

	  def show
	    respond_with @order = Order.find(params[:id])
	  end

	end
</pre>

That's it. Restfulie will take care of rendering a valid representation according to content negotiation. You can configure the rendering process through a custom tokamak view:

<pre>
	collection(@orders) do |collection|
	  collection.values do |value|
		value.id = orders_url
	  end
	  
	  collection.link("create", orders_url)
	  collection.members
	end
</pre>

You can go through an entire application by "watching this video":http://guilhermesilveira.wordpress.com or "downloading an example application contained within the restfulie ":http://github.com/caelum/restfulie/tree/master/full-examples/rest_from_scratch/

h2. Simple client example

The following example is a partial REST client implementation that navigates through some relations:

<pre>
order = Restfulie.at('http://localhost:3000/orders/1').get!
order.items.each { |item| puts items }
receipt = order.payment.post! { :amount => 500 }
puts receipt.id
</pre>

In order to create a full REST client, "watch this video":http://guilhermesilveira.wordpress.com.

h2. Full examples

You can view an entire application running Restfulie under *spec/integration/order/server* and *spec/integration/order/client* in this git repository.

"You can also download a full example of a REST based agent and server":http://github.com/caelum/restfulie/tree/master/full-examples/rest_from_scratch/ using Restfulie, according to the Rest Architecture Maturity Model.

h2. Documentation

Appart from the simple server and client examples provided here, you can find the following links useful:

* "RDocs":http://rdoc.info/projects/caelum/restfulie
* "Official website":http://restfulie.caelumobjects.com
* "How-tos":http://restfulie.caelumobjects.com/caelumobjects-restful-rails.pdf
* "Buying through Rest: Rest to the enterprise (video)":http://guilhermesilveira.wordpress.com/2010/04/13/buying-through-rest-applying-rest-to-the-enterprise/

h2. Installing

Execute:

<pre>
gem install restfulie
</pre>

For use in Rails 2.3, make sure to require the responders_backport gem in addition to the restfulie gem, either in environment.rb or in the Gemfile.

h2. Building the project

If you want to build the project and run its tests, remember to install all (client and server) required gem. 
"Bundler":http://gembundler.com/ is required to easily manage dependencies

<pre>
bundle install
rake test:spec test:integration
</pre>

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-11770776-1");
pageTracker._trackPageview();
} catch(err) {}</script>

h2. Contributions

Restfulie was created and is maintained by "Caelum":http://caelumobjects.com, and has received enormous contributions from all those developers:

Project Leader
Guilherme Silveira, "Caelum":http://www.caelum.com.br

Caue Guerra, caelum
George Guimaraes, abril and plataforma
Fabio Akita
Diego Carrion
Leandro Silva
Gavin-John Noonan
Antonio Marques
Luis Cipriani, abril
Everton Ribeiro, abril
Paulo Ahagon, abril
Elomar França
Thomas Stefano
"David Paniz":"http://www.caelum.com.br"
"Caike Souza":"http://www.caikesouza.com/blog"

h2. Rails 2

If you want to use Restfulie with Rails2, please use any release up to 0.9.2 and its minor releases.