simple server side description

README.textile

@@ -1,20 +1,21 @@
 h1. Web site
 
 Restfulie's website can be found at "http://restfulie.caelum.com.br":http://restfulie.caelum.com.br
+Mikyung's, a REST agent framework built on top of Restfulie can be seen at "http://github.com/caelum/mikyung":http://github.com/caelum/mikyung.
 
 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 based services and this gem allows you to do it really fast.
+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 aware resource based clients
-#  Easy --> hypermedia aware resource based services
+#  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 your URIs
-#  HATEOAS --> services that you consume will not affect your software whenever they change part of their flow or URIs
+#  HATEOAS --> resources that you consume will not affect your software whenever they change part of their flow or URIs
+#  Adaptability --> clients are able to adapt to your changes
 
 h2. Installing
 
@@ -31,6 +32,60 @@ For server side usage, execute:
 gem install restfulie
 </pre>
 
+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>
+	describe_collection(@orders) do |collection|
+	  collection.id = orders_url
+	  collection.links << link( :rel => :create,  :href => orders_url )
+	  collection.describe_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. Download source example
+
+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/mikyung using Restfulie and Mikyung, according to the Rest Architecture Maturity Model.
+
+h2. Building the project
+
 If you want to build the project and run its tests, remember to install all (client and server) required gems and:
 
 <pre>