restfulie 0.1.0.beta1 → 0.1

data/README.textile

@@ -1,138 +1,126 @@
-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.
+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.
 
-h2. Why would I use restfulie?
+h1. Restfulie: client-side
 
-#  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:
+Here you can see how to access a resource and its services through the restfulie API:
 
 <pre>
-	class OrdersController < ApplicationController
-	  include Restfulie::Server::ActionController::Base
+order = Order.from_web resource_uri      # retrieves order resource (xml/atom/json support)
 
-	  respond_to :atom, :html, :xml, :commerce, :opensearch
+puts "Order price is #{order.price}"
 
-	  def index
-	    respond_with @orders = Order.all
-	  end
+order.pay payment                        # sends a post request to pay this order
 
-	  def show
-	    respond_with @order = Order.find(params[:id])
-	  end
-
-	end
+order.cancel                             # sends a delete request
 </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:
+h1. Restfulie: server-side
+
+This is a simple example how to make your state changes available to your resource consumers:
 
 <pre>
-	collection(@orders) do |collection|
-	  collection.values do |value|
-		value.id = orders_url
+	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
-	  
-	  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
+h2. Installing
 
-The following example is a partial REST client implementation that navigates through some relations:
+Just add in your environment.rb the following line:
 
 <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
+config.gem "restfulie", :source => "http://gemcutter.org"
 </pre>
 
-In order to create a full REST client, "watch this video":http://guilhermesilveira.wordpress.com.
+Execute:
+<pre>rake gems:install</pre>
 
-h2. Full examples
+or, if you prefer to install as a plugin:
 
-You can view an entire application running Restfulie under *spec/integration/order/server* and *spec/integration/order/client* in this git repository.
+script/plugin install git://github.com/caelum/restfulie.git
 
-"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. Typical Restful Example
 
-h2. Documentation
+Trying to follow the definition of a restful application supporting resources with hypermedia content, a typical restful resource would be:
 
-Appart from the simple server and client examples provided here, you can find the following links useful:
+<pre>
+<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>
+</pre>
 
-* "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. Client Usage
 
-h2. Installing
+One should first acquire the representation from the server through your common GET process 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>
 
-Execute:
+And now you can invoke all those actions in order to change your resource's state:
 
 <pre>
-gem install restfulie
+order.refresh
+order.update
+order.destroy
+order.pay(payment)
 </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.
+Note that:
+* refresh is get
+* update is put (and you have to put everything back)
+* destroy is delete
+* pay (unknown methods) is post
+
+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.
+
+
+h2. Help
+
+If you are looking for or want to help, let us know at the mailing list: http://groups.google.com/group/restfulie
+
+h2. How to customize your request
+
+By default, restfulie uses the following table:
 
-h2. Building the project
+* 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 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
+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>
-bundle install
-rake test:spec test:integration
+order.update(:method=>"post")
 </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.
+h2. License
+
+/***
+ * Copyright (c) 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.
+ */

data/Rakefile

@@ -2,18 +2,14 @@ require 'rubygems'
 require 'rubygems/specification'
 require 'rake'
 require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'rspec'
-require 'rspec/core'
-require 'rspec/core/rake_task'
-require File.expand_path('lib/restfulie')
+require 'spec/rake/spectask'
 
 GEM = "restfulie"
-GEM_VERSION = Restfulie::VERSION
-SUMMARY  = "Hypermedia aware resource based library in ruby (client side) and ruby on rails (server side)."
-AUTHOR   = "Guilherme Silveira, Caue Guerra, Luis Cipriani, Everton Ribeiro, George Guimaraes, Paulo Ahagon, Several contributors"
-EMAIL    = "guilherme.silveira@caelum.com.br"
-HOMEPAGE = "http://restfulie.caelumobjects.com"
+GEM_VERSION = "0.1"
+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"
+HOMEPAGE = "http://github.com/caelum/restfulie"
 
 spec = Gem::Specification.new do |s|
   s.name = GEM
@@ -21,114 +17,27 @@ spec = Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.summary = SUMMARY
   s.require_paths = ['lib']
-  s.files = FileList['lib/**/*.rb', '[A-Z]*', 'lib/**/*.rng'].to_a
-  s.add_dependency("nokogiri", [">= 1.4.2"])
-  s.add_dependency("actionpack", [">= 2.3.2"])
-  s.add_dependency("activesupport", [">= 2.3.2"])
-  s.add_dependency("json_pure", [">= 1.2.4"])
+  s.files = FileList['lib/**/*.rb', '[A-Z]*'].to_a
+
+  # s.add_dependency(%q<rubigen>, [">= 1.3.4"])
 
   s.author = AUTHOR
   s.email = EMAIL
   s.homepage = HOMEPAGE
 end
 
-module FakeServer
-  def self.wait_server(port=3000)
-    (1..15).each do 
-      begin
-        Net::HTTP.get(URI.parse("http://localhost:#{port}/"))
-        return
-      rescue
-        sleep 1
-      end
-    end
-    raise "Waited for the server but it did not finish"
-  end
-  
-  def self.start_sinatra
-    IO.popen("cd tests && ruby ./spec/requests/fake_server.rb") do |pipe|
-      wait_server 4567
-      yield
-      Process.kill 'INT', pipe.pid
-    end
-  end
-  
-  def self.run(setup, process)
-    success = IO.popen(setup) do |pipe|
-      wait_server
-      success = system "rake spec"
-      Process.kill 'INT', pipe.pid
-      success
-    end
-    if !success
-      raise "Some of the specs failed"
-    end
-  end
-  
-  def self.start_server_and_run_spec(target_dir)
-    success = Dir.chdir(File.join(File.dirname(__FILE__), target_dir)) do
-      system('rake db:drop db:create db:migrate')
-      self.run "rails server", "rake spec"
-    end
-  end
-  
-end
-
-# optionally loads a task if the required gems exist
-def optionally
-  begin
-    yield
-  rescue LoadError; end
-end
-
-namespace :test do
-  
-  task :spec do
-    FakeServer.start_sinatra do
-      FakeServer.start_server_and_run_spec "tests"
-    end
-  end
-  
-  task :integration do
-    FakeServer.start_server_and_run_spec "full-examples/rest_from_scratch/part_1"
-    FakeServer.start_server_and_run_spec "full-examples/rest_from_scratch/part_2"
-    FakeServer.start_server_and_run_spec "full-examples/rest_from_scratch/part_3"
-  end
-  
-  task :sinatra do
-    FakeServer.start_sinatra do
-      puts "Press something to quit"
-      gets
-    end
-  end
-  
-  task :all => ["spec","integration"]
-  
-end
-
-RSpec::Core::RakeTask.new(:spec) do |t|
-  # t.spec_files = FileList['spec_*.rb']
-  t.spec_opts = ['--colour', '--format progress']
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = %w(-fs -fh:doc/specs.html --color)
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end
 
-Rake::RDocTask.new("rdoc") do |rdoc|
-   rdoc.options << '--line-numbers' << '--inline-source'
-end
-
-optionally do
-  require 'yard'
-  YARD::Rake::YardocTask.new do |t|
-    t.files   = ['lib/restfulie/**/*.rb', 'README.textile']
-  end
-end
-
 desc "Install the gem locally"
 task :install => [:package] do
-  sh %{gem install pkg/#{GEM}-#{GEM_VERSION} -l}
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
 end
 
 desc "Create a gemspec file"
@@ -139,8 +48,4 @@ task :make_spec do
 end
 
 desc "Builds the project"
-task :build => ["install", "test:spec"]
-
-desc "Default build will run specs"
-task :default => :build
-
+task :build => :spec

data/lib/restfulie.rb

@@ -1,34 +1,194 @@
-$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
+require 'net/http'
+require 'uri'
 
-require 'restfulie/version'
-require 'restfulie/common'
-require 'restfulie/client'
-require 'restfulie/server'
-
-# Shortcut to RestfulieDsl
 module Restfulie
+  def to_json
+    super :methods => :following_states
+  end
 
-  # creates a new entry point for executing requests
-  def self.at(uri)
-    Restfulie.use.at(uri)
+  def to_xml(options = {})
+    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
+        end
+      end
+    end
   end
 
-  def self.using(&block)
-    RestfulieUsing.new.instance_eval(&block)
+  def create_method(name, &block)
+    self.class.send(:define_method, name, &block)
   end
-  
-  def self.use(&block)
-    if block_given?
-      Restfulie::Client::Dsl.new.instance_eval(&block)
-    else
-      Restfulie::Client::Dsl.new
+
+end
+
+module ActiveRecord
+  class Base
+
+    include Restfulie
+    attr_accessor :_possible_states
+    attr_accessor :_came_from
+
+    def self.add_states(result, states)
+      result._possible_states = {}
+      states.each do |state|
+        result._possible_states[state["rel"]] = state
+      end
+      def result.respond_to?(sym)
+        has_state(sym.to_s) || super(sym)
+      end
+
+      def result.has_state(name)
+        !@_possible_states[name].nil?
+      end
+      
+      states.each do |state|
+        name = state["rel"]
+        self.module_eval do
+          def current_method
+            caller[0]=~/`(.*?)'/
+            $1
+          end
+          def temp_method(options = {}, &block)
+            name = current_method
+            state = _possible_states[name]
+            data = options[:data] || {}
+            url = URI.parse(state["href"])
+            get = false
+
+            # gs: i dont know how to meta play here! i suck
+            if options[:method]=="delete"
+              req = Net::HTTP::Delete.new(url.path)
+            elsif options[:method]=="put"
+              req = Net::HTTP::Put.new(url.path)
+            elsif options[:method]=="get"
+              req = Net::HTTP::Get.new(url.path)
+              get = true
+            elsif options[:method]=="post"
+              req = Net::HTTP::Post.new(url.path)
+            elsif ['destroy','delete','cancel'].include? name
+              req = Net::HTTP::Delete.new(url.path)
+            elsif ['refresh', 'reload', 'show', 'latest'].include? name
+              req = Net::HTTP::Get.new(url.path)
+              get = true
+            else
+              req = Net::HTTP::Post.new(url.path)
+            end
+
+            req.set_form_data(data)
+            req.add_field("Accept", "text/xml") if _came_from == :xml
+
+            http = Net::HTTP.new(url.host, url.port)
+            response = http.request(req)
+            return yield(response) if !block.nil?
+            if get
+              case response.content_type
+              when "application/xml"
+                content = response.body
+                hash = Hash.from_xml content
+                return hash if hash.keys.length == 0
+                raise "unable to parse an xml with more than one root element" if hash.keys.length>1
+                key = hash.keys[0]
+                type = key.camelize.constantize
+                return type.from_xml content
+              else
+                raise :unknown_content_type
+              end
+            end
+            response
+
+          end
+          alias_method name, :temp_method
+          undef :temp_method
+        end
+      end
+      
+      result
+    end
+
+    def self.from_web(uri)
+      url = URI.parse(uri)
+      req = Net::HTTP::Get.new(url.path)
+      http = Net::HTTP.new(url.host, url.port)
+      res = http.request(req)
+      raise :invalid_request, res if res.code != "200"
+      case res.content_type
+      when "application/xml"
+        self.from_xml res.body
+      when "application/json"
+        self.from_json res.body
+      else
+        raise :unknown_content_type
+      end
+    end
+
+    # basic code from Matt Pulver
+    # found at http://www.xcombinator.com/2008/08/11/activerecord-from_xml-and-from_json-part-2/
+    # addapted to support links
+    def self.from_hash( hash )
+      h = {}
+      h = hash.dup if hash
+      links = nil
+      h.each do |key,value|
+        case value.class.to_s
+        when 'Array'
+          if key=="link"
+            links = h[key]
+            h.delete("link")
+          else
+            h[key].map! { |e| reflect_on_association(key.to_sym ).klass.from_hash e }
+          end
+        when /\AHash(WithIndifferentAccess)?\Z/
+          if key=="link"
+            links = [h[key]]
+            h.delete("link")
+          else
+            h[key] = reflect_on_association(key.to_sym ).klass.from_hash value
+          end
+        end
+      end
+      result = self.new h
+      add_states(result, links) unless links.nil?
+      result
+    end
+
+    def self.from_json( json )
+      from_hash safe_json_decode( json )
+    end
+
+    # The xml has a surrounding class tag (e.g. ship-to),
+    # but the hash has no counterpart (e.g. 'ship_to' => {} )
+    def self.from_xml( xml )
+      hash = Hash.from_xml xml
+      head = hash[self.to_s.underscore]
+      result = self.from_hash head
+      return nil if result.nil?
+      result._came_from = :xml
+      result
     end
   end
-  
 end
 
-class RestfulieUsing
-  def method_missing(sym, *args)
-    @current = "Restfulie::Client::HTTP::#{sym.to_s.classify}".constantize.new(@current || Restfulie::Client::HTTP::RequestAdapter.new, *args)
-  end
+def safe_json_decode( json )
+  return {} if !json
+  begin
+    ActiveSupport::JSON.decode json
+  rescue ; {} end
 end
+# end of code based on Matt Pulver's