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":http://github.com/caelum/mikyung.

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/full-restfulie-examples 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>

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.