restfulie 0.1 → 0.2

data/README.textile

@@ -1,13 +1,21 @@
 h1. 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.
+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.
+
+h2. Why would I use restfulie?
+
+1. Easy --> writing hypermedia aware resource based clients
+2. Easy --> hypermedia aware resource based services
+3. Small -> it's not a bloated solution with a huge list of APIs
+4. HATEOAS --> clients you are unaware of will not bother if you change your URIs
+5. HATEOAS --> services that you consume will not affect your software whenever they change part of their flow or URIs
 
 h1. Restfulie: client-side
 
-Here you can see how to access a resource and its services through the restfulie API:
+Example on accessing a resource and its services through the restfulie API:
 
 <pre>
-order = Order.from_web resource_uri      # retrieves order resource (xml/atom/json support)
+order = Order.from_web resource_uri
 
 puts "Order price is #{order.price}"
 
@@ -21,14 +29,59 @@ h1. Restfulie: server-side
 This is a simple example how to make your state changes available to your resource consumers:
 
 <pre>
-	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
+class Order < ActiveRecord::Base
+  def following_transitions
+    transitions = []
+    transitions << [:show, {}]
+    transitions << [:destroy, {}] if can_cancel?
+    transitions << [:pay, {:id => id}] if can_pay?
+    transitions << [:show, {:controller => :payments, :payment_id => payment.id }] if paid?
+    transitions
+  end
+end
+</pre>
+
+*Do not forget to create a migration with a string field named status for your resource:*
+
+<pre>
+scripts/generate migration add_status_to_order	
+</pre>
+
+Content:
+
+<pre>
+class AddStatusToOrder < ActiveRecord::Migration
+  def self.up
+    add_column :orders, :status, :string
+	Order.all.each do |order|
+		order.status = "unpaid"
+		order.save
+	end
+  end
+
+  def self.down
+    remove_column :orders, :status
+  end
+end
+</pre>
+
+Or simply define a status reader and writer on your own.
+
+
+
+h2. Restfulie server-side: state machine
+
+For those willing to implement a more complex or advanced state machine, you can use the dsl-like api:
+
+<pre>
+class Order < ActiveRecord::Base
+  state :unpaid, :allow => [:latest, :pay, :cancel]
+  state :cancelled, :allow => :latest
+
+  transition :latest, {:action => :show}
+  transition :cancel, {:action => :destroy}, :cancelled
+  transition :pay, {}, :preparing
+end
 </pre>
 
 h2. Installing
@@ -39,33 +92,35 @@ Just add in your environment.rb the following line:
 config.gem "restfulie", :source => "http://gemcutter.org"
 </pre>
 
-Execute:
+And then execute:
 <pre>rake gems:install</pre>
 
-or, if you prefer to install as a plugin:
+or, if you prefer to install it as a plugin:
 
-script/plugin install git://github.com/caelum/restfulie.git
+<pre>script/plugin install git://github.com/caelum/restfulie.git</pre>
 
-h2. Typical Restful Example
+h2. Typical hypermedia aware example
 
-Trying to follow the definition of a restful application supporting resources with hypermedia content, a typical restful resource would be:
+Trying to follow the definition of a RESTful application supporting resources with hypermedia content, a resource would be:
 
 <pre>
 <order>
 	<product>basic rails course</product>
-	<product>restful training</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="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>
 </pre>
 
 h2. Client Usage
 
-One should first acquire the representation from the server through your common GET process and process it through the usual from_* methods:
+One should first acquire the representation from the server through your common GET request and process it through the usual from_* methods:
 <pre>xml = Net::HTTP.get(URI.parse('http://www.caelum.com.br/orders/1'))
 order = Order.from_xml(xml)</pre>
+or use the restfulie *from_web*:
+<pre>order = Order.from_web 'http://www.caelum.com.br/orders/1'</pre>
 
 And now you can invoke all those actions in order to change your resource's state:
 
@@ -73,7 +128,7 @@ And now you can invoke all those actions in order to change your resource's stat
 order.refresh
 order.update
 order.destroy
-order.pay(payment)
+order.pay
 </pre>
 
 Note that:
@@ -84,28 +139,252 @@ Note that:
 
 h2. 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.
+Restfulie currently supports full xml+atom, partial xml+rel and will soon expand its support to json+links.
 
 
 h2. Help
 
-If you are looking for or want to help, let us know at the mailing list: http://groups.google.com/group/restfulie
+If you are looking for or want to help, let us know at the mailing list:
+
+"http://groups.google.com/group/restfulie":http://groups.google.com/group/restfulie
+
+h2. Client-side configuration: how to customize your request
 
-h2. How to customize your request
+h3. HTTP verbs
 
 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
+* 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':
 
+<pre>order.update(:method=>"post")</pre>
+
+h3. Request parameters
+
+If you want to send extra parameters, you can do it through the *data* parameter:
+
+<pre>order.pay(:data => {:payment => my_payment})</pre>
+
+The parameters will be serialized either to xml or json according to which format was used to deserialize the order at first place.
+
+h3. Executing another GET request
+
+If your method executes another GET request, it will automatically deserialize its result as:
+
+<pre>order = Order.from_web order_uri
+payment = order.check_payment_info</pre>
+
+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
+
+<pre>order = Order.from_web order_uri
+successful = order.check_payment_info do |response|
+  return response.code==200
+end</pre>
+
+h2. Server-side configuration
+
+There are two different approaches that can be combined to create a full hypermedia aware resource based service, including awareness of its states and transitions.
+
+h3. The following available transitions method
+
+The most easy way to use restfulie is to write the *following_transitions* method.
+It should return a list of possible transitions, where each transition is identified by an array of its name and definition.
+
+The next example shows how to define a transition which will map to the current controller, action show:
+
+<pre>
+def following_transitions
+  transitions = []
+  transitions << [:show, {}]
+  transitions
+end
+</pre>
+
+Which will generate an hyperlink as
+
+<pre><atom:link rel="show" rel="http://yourserver/orders/15" /></pre>
+
+h3. Customizing the rel name
+
+You can also override the action used, but still keep the rel
+
 <pre>
-order.update(:method=>"post")
+def following_transitions
+  transitions = []
+  transitions << [:cancel, { :action => :destroy }]
+  transitions
+end
 </pre>
 
+Which will generate an hyperlink as
+
+<pre><atom:link rel="cancel" rel="http://yourserver/orders/15" /></pre>
+
+h3. Example
+
+A full example showing all capabilities of this method follows:
+
+<pre>
+def following_transitions
+  transitions = []
+  transitions << [:show, {}]
+  transitions << [:destroy, {}] if can_cancel?
+  transitions << [:pay, {:id => id}] if can_pay?
+  transitions << [:show, {:controller => :payments, :payment_id => payment.id }] if paid?
+  transitions
+end
+</pre>
+
+h2. Defining the state machine and its transitions
+
+The second way of defining your available transitions is to explicitely define the states and transitions.
+
+By using this approach, one has to define a new column named *status* in a database migration file.
+
+The first step involves defining all your states, each one with its own name and possible transitions, as:
+
+<pre>
+	state :state_name, :allow => [ :first_transition_name, :second_transition_name]
+</pre>
+
+The following example shows all possible states for an order:
+
+<pre>
+class Order < ActiveRecord::Base
+	state :unpaid, :allow => [:latest, :pay, :cancel]
+	state :cancelled, :allow => :latest
+	state :received, :allow => [:latest, :check_payment_info]
+	state :preparing, :allow => [:latest, :check_payment_info]
+	state :ready, :allow => [:latest, :receive, :check_payment_info]
+end
+</pre>
+
+Now its time to define which controller and action each transition invokes, in a much similar way to
+the transition definitions in the following_transitions method:
+
+<pre>
+class Order < ActiveRecord::Base
+end
+</pre>
+
+Once a transition has been given a name, its name can be used in the following_transitions method also.
+The next example does not configure the transition because it was already defined, only adding it to the
+list of available transition whenever the *can_pay?* method returns true:
+
+<pre>
+class Order < ActiveRecord::Base
+	transition :pay, {:action => pay_this_order, :controller => :payments}, :preparing
+
+	def following_transitions
+	  transitions = []
+	  transitions << :pay if can_pay?
+	  transitions
+	end
+end
+</pre>
+
+Note that whenever one defines a transition, there is a third - optional - argument, this is the
+transition's target's state. Whenever the method *order.pay* method is invoked in the *server*, it will
+automatically change the order's status to *preparing*.
+
+You can download the server side example to see the complete code.
+
+The last usage of the transition definition involves passing a block which receives the element in which
+the transition URI's is required. The block should return all the necessary information for retrieving the URI, now having access to your element's instance variables:
+
+<pre>
+class Order < ActiveRecord::Base
+	transition :check_payment_info do |order|
+	   {:controller => :payments, :action => :show, :order_id => order.id, :payment_id => order.payments[0].id, :rel => "check_payment_info"}
+	end
+end
+</pre>
+  
+h3. 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
+
+<pre>
+	<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>
+</pre>
+
+You can do it by passing the *use_name_based_link* argument:
+
+<pre>
+    order.to_xml(:controller => my_controller, :use_name_based_link => true)
+</pre>
+
+h2. Team
+
+Restfulie was created and is maintained within Caelum by
+
+Projetct Founder
+* "Guilherme Silveira":mailto:guilherme.silveira@caelum.com.br
+
+Active Commiters
+* "Caue Guerra":mailto:caue.guerra@gmail.com
+* "Guilherme Silveira":mailto:guilherme.silveira@caelum.com.br
+
+Contributors
+* Diego Carrion
+* Leandro Silva
+* Gavin-John Noonan
+
+h2. 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":http://restfulie-test.heroku.com
+* 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":http://restfulie-client.heroku.com
+* 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.check_payment_info_
+
+In order to pay do not forget to send the parameter *payment* with a value as
+
+<pre>
+ <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>
+</pre>
+
+
+h3. Sources
+
+"Client":http://github.com/caelum/restfulie-client
+"Server":http://github.com/caelum/restfulie-test
+
+
 h2. License
 
 /***

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
 require 'spec/rake/spectask'
 
 GEM = "restfulie"
-GEM_VERSION = "0.1"
+GEM_VERSION = "0.2"
 SUMMARY = "This is a small cute plugin to show how to implement hypermedia based services in a easy way using rails."
 AUTHOR = "Guilherme Silveira, Caue Guerra"
 EMAIL = "guilherme.silveira@caelum.com.br"

data/lib/restfulie.rb

@@ -5,28 +5,51 @@ module Restfulie
   def to_json
     super :methods => :following_states
   end
-
+  
   def to_xml(options = {})
+    return super unless respond_to?(:status)
+
     controller = options[:controller]
     return super if controller.nil?
-    
+        
     options[:skip_types] = true
     super options do |xml|
-      if respond_to?(:following_states)
-        states = following_states
-        states = [states] if states.class.to_s != 'Array'
-        states.each do |action|
-          rel = action[:action]
-          if action[:rel]
-            rel = action[:rel]
-            action[:rel] = nil
-          end
-          translate_href = controller.url_for(action)
-          if options[:use_name_based_link]
-            xml.tag!(rel, translate_href)
-          else
-            xml.tag!('atom:link', 'xmlns:atom' => 'http://www.w3.org/2005/Atom', :rel => rel, :href => translate_href)
-          end
+      possible_following = []
+      default_transitions_map = self.class._transitions_for(status.to_sym)
+      default_transitions = default_transitions_map[:allow] unless default_transitions_map.nil?
+    
+      possible_following += default_transitions unless default_transitions.nil?
+      possible_following += self.following_transitions if self.respond_to?(:following_transitions)
+      
+      return super if possible_following.empty?
+      
+      possible_following.each do |possible|
+        if possible.class.name=="Array"
+          name = possible[0]
+          result = [possible[1], nil]
+        else
+          name = possible
+          result = self.class._transitions(name.to_sym)
+        end
+    
+        if result[0]
+          action = result[0]
+          body = result[1]
+          action = body.call(self) if body
+
+          rel = action[:rel] || name || action[:action]
+          action[:rel] = nil
+        else
+          action = {}
+          rel = name
+        end
+    
+        action[:action] ||= name
+        translate_href = controller.url_for(action)
+        if options[:use_name_based_link]
+          xml.tag!(rel, translate_href)
+        else
+          xml.tag!('atom:link', 'xmlns:atom' => 'http://www.w3.org/2005/Atom', :rel => rel, :href => translate_href)
         end
       end
     end
@@ -35,7 +58,14 @@ module Restfulie
   def create_method(name, &block)
     self.class.send(:define_method, name, &block)
   end
-
+  
+  def move_to(name)
+    transitions = self.class._transitions_for(self.status.to_sym)[:allow]
+    raise "Current state #{status} is invalid in order to execute #{name}. It must be one of #{transitions}" unless transitions.include? name
+    result = self.class._transitions(name)[2]
+    self.status = result.to_s unless result.nil?
+  end
+  
 end
 
 module ActiveRecord
@@ -44,6 +74,45 @@ module ActiveRecord
     include Restfulie
     attr_accessor :_possible_states
     attr_accessor :_came_from
+    
+    def self._transitions_for(state)
+      @@states[state]
+    end
+    
+    def self._transitions(name)
+      [@@transitions[name], @@bodies[name], @@results[name]]
+    end
+    
+    @@states = {}
+    @@transitions = {}
+    @@bodies = {}
+    @@results = {}
+    
+    def self.state(name, options)
+      if name.class==Array
+        name.each do |simple|
+          self.state(simple, options)
+        end
+      else
+        options[:allow] = [options[:allow]] unless options[:allow].class == Array
+        @@states[name] = options
+      end
+    end
+
+    def self.transition(name, options = {}, result = nil, &body)
+      @@transitions[name] = options
+      @@bodies[name] = body
+      @@results[name] = result unless result == nil
+      defined = self.respond_to?(name)
+      if !defined
+        self.send(:define_method, name) do |*args|
+          self.status = result.to_s unless result == nil
+        end
+        self.send(:define_method, "can_#{name}2?") do
+          puts "executing can_#{name}2?"
+        end
+      end
+    end
 
     def self.add_states(result, states)
       result._possible_states = {}
@@ -162,6 +231,7 @@ module ActiveRecord
             h[key] = reflect_on_association(key.to_sym ).klass.from_hash value
           end
         end
+        h.delete("xmlns") if key=="xmlns"
       end
       result = self.new h
       add_states(result, links) unless links.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: restfulie
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Guilherme Silveira, Caue Guerra
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-03 00:00:00 -02:00
+date: 2009-11-11 00:00:00 -02:00
 default_executable: 
 dependencies: []