rested 0.2.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.swo
+*.swp
+pkg

data/README.rdoc

@@ -0,0 +1,96 @@
+= rested
+
+* http://github.com/chetan/rested
+
+== DESCRIPTION:
+
+Ruby library built on top of httpclient for working with RESTful APIs.
+
+== DOCUMENTATION:
+
+Documentation is available online at at rdoc.info[http://rdoc.info/projects/chetan/rested]
+
+== FEATURES:
+
+== SYNOPSIS:
+
+  class Foo < Rested::Entity
+    base_url    "http://api.example.com/entities/"
+    endpoint    "foo"
+    user        "user@example.com"
+    pass        "foobar"
+
+    field     :id, :baz, :bar
+  end
+  
+  foo = Foo.find(1)
+  foo.baz = "frobnicator"
+  foo.save!
+  
+  moe = Foo.new
+  moe.bar = "curly"
+  moe.save!
+  puts "new id is #{moe.id}"
+  
+  # to upload a file
+  moe.add_file("param_name", "/path/to/file")
+  moe.save!
+  
+  # non-entity based example
+  
+  class Baz < Rested::Base
+    base_url    "http://api.example.com/methods/"
+    user        "user@example.com"
+    pass        "foobar"
+
+    def self.search(terms)
+      params = {}
+      params["terms"] = terms
+      ret = post("/search", params)
+      ret["search_results"]
+    end
+
+  end
+  
+
+== REQUIREMENTS:
+
+* httpclient
+* json
+
+== INSTALL:
+
+With gemcutter:
+
+  sudo gem install rested
+
+Without gemcutter:
+
+  git clone git://github.com/chetan/rested.git
+  cd rested
+  sudo rake install
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Better Advertising, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,28 @@
+
+begin
+  require 'rubygems'
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "rested"
+    gemspec.summary = "Ruby library for working with RESTful APIs"
+    gemspec.description = "Ruby library built on top of httpclient for working with RESTful APIs."
+    gemspec.email = "chetan@betteradvertising.com"
+    gemspec.homepage = ""
+    gemspec.authors = ["Chetan Sarva"]
+    gemspec.add_dependency('httpclient', '>= 2.1.5.2')
+    gemspec.add_dependency('json', '>= 1.4.2')
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end
+
+require "rake/testtask"
+desc "Run unit tests"
+Rake::TestTask.new("test") { |t|
+    #t.libs << "test"
+    t.ruby_opts << "-rubygems"
+    t.pattern = "test/**/*_test.rb"
+    t.verbose = false
+    t.warning = false
+}

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/rested/base.rb

@@ -0,0 +1,97 @@
+
+require 'rubygems'
+require 'httpclient'
+require 'json'
+
+module Rested
+    
+    module BaseMethods
+        
+        # override this method to customize HTTPClient
+        def setup_client
+            @client = ::HTTPClient.new
+            if self.user and self.pass then
+                @client.set_auth(self.base_url, self.user, self.pass)
+            end
+            @client.debug_dev = STDOUT if Rested.debug
+            @client
+        end
+
+        def client
+            @client ||= setup_client()
+        end
+    
+        def get(uri, params = nil)
+            url = self.base_url + uri
+            Rested.log_out{"GET #{url}"}
+            Rested.log_out{"    params: " + params.inspect}
+            handle_response(self.client.get(url, params))
+        end
+        
+        def post(uri, params = nil)
+            url = self.base_url + uri
+            Rested.log_out{"POST #{url}"}
+            Rested.log_out{"     params: " + params.inspect}
+            handle_response(self.client.post(url, params))
+        end
+        
+        def delete(uri)
+            url = self.base_url + uri
+            Rested.log_out{"DELETE #{url}"}
+            res = self.client.delete(url)
+            handle_error(res) if message.status >= 400
+            return res.status == 200
+        end
+
+        def handle_response(message)
+            handle_error(message) if message.status >= 400
+            Rested.log_in{ puts; "HTTP/#{message.version} #{message.status} #{message.reason}"}
+            Rested.log_in{ message.header.all.each{|h| Rested.log_in("#{h[0]}: #{h[1]}")}; puts }
+            decode_response(message)
+        end
+        
+        def decode_response(message)
+            ct = message.contenttype
+            if ct =~ /json|javascript/ then
+                decode_json_response(message)
+            elsif ct =~ /xml/ then
+                decode_xml_response(message)
+            else
+                Rested.log_in { "\n" + message.content }
+                raise "Unknown response type"
+            end
+        end
+        
+        def decode_json_response(message)
+            begin
+                JSON.load(message.content)
+            rescue => ex
+                nil
+            end
+        end
+        
+        def decode_xml_response(message)
+            raise NotImplementedError # TODO
+        end
+
+        def handle_error(message)
+            Rested.log_in{ puts; "HTTP/#{message.version} #{message.status} #{message.reason}"}
+            Rested.log_in{ message.header.all.each{|h| Rested.log_in("#{h[0]}: #{h[1]}")}; puts }
+            raise Rested::Error.new(message)
+        end
+        
+    end
+    
+    class Base
+    
+        rattr_accessor :base_url, :user, :pass
+
+        class << self
+            include BaseMethods     
+        end
+        
+        include BaseMethods
+    
+    end
+
+end

data/lib/rested/debug.rb

@@ -0,0 +1,59 @@
+module Rested
+    
+    @debug = false
+    
+    def self.debug(val=nil)
+        return @debug unless val
+        if val == true then
+            @debug = STDOUT
+        else
+            @debug = val
+        end
+    end
+    
+    def self.debug=(val)
+        self.debug(val)
+    end
+
+    def self.log(msg = nil, &block)
+        return unless @debug
+        if block_given? then
+            s = yield
+            return if not s.kind_of? String
+            @debug.puts(s)
+        elsif not msg.nil? then
+            @debug.puts(msg)
+        end
+    end
+    
+    def self.log_do(msg = nil, &block)
+        if block_given? then
+            s = yield
+            return if not s.kind_of? String
+            log { "* " + s }
+        else
+            log("* #{msg}")
+        end
+    end
+    
+    def self.log_in(msg = nil, &block)
+        if block_given? then
+            s = yield
+            return if not s.kind_of? String
+            log { "< " + s }
+        else
+            log("< #{msg}")
+        end
+    end
+    
+    def self.log_out(msg = nil, &block)
+        if block_given? then
+            s = yield
+            return if not s.kind_of? String
+            log { "> " + s }
+        else
+            log("> #{msg}")
+        end
+    end
+    
+end

data/lib/rested/entity.rb

@@ -0,0 +1,247 @@
+require File.dirname(__FILE__) + '/ext'
+require File.dirname(__FILE__) + '/base'
+
+module Rested
+  
+  class Entity < Base
+
+    rattr_accessor :endpoint, :id_field
+    attr_accessor :errors
+    Entity.id_field(:id)
+    
+    class << self
+
+      attr_reader :before_filters, :after_filters
+
+      def before_filters
+        @before_filters ||= []
+      end
+
+      def after_filters
+        @after_filters ||= []
+      end
+
+      def before_save(&block)
+        before_filters << block
+      end
+
+      def after_save(&block)
+        after_filters << block
+      end
+      
+      def id_field
+        @id_field ||= inherit_static_from_super(:id_field) || nil
+      end
+      
+      def inherit_static_from_super(sym)
+        if superclass.respond_to? sym then
+          val = superclass.send(sym)
+          return val if val.kind_of? Symbol
+          return val.dup if not val.nil?
+        end
+        return nil
+      end
+      
+      def fields
+        @fields ||= inherit_static_from_super(:fields) || []
+      end
+
+      def field(*args)
+        args.each do |f|
+          add_field(f) unless fields.include? f 
+        end
+      end
+
+      def delimited_fields
+        @delimited_fields ||= {}
+      end
+
+      def delimited_field(field, delimiter = ',')
+        unless fields.include? field
+          delimited_fields[field] = delimiter
+          add_field(field)
+        end
+      end
+
+      def add_field(field)
+        self.fields << field
+        attr_accessor field
+      end
+
+      def find(id = nil, masquerade = nil)
+        uri = self.endpoint
+        uri += "/#{id}" if not id.nil?
+        begin
+          json = get(uri, :masquerade => masquerade)
+        rescue Rested::Error => ex
+          if ex.message =~ /Invalid/ then
+            raise ObjectNotFound.new(ex.http_response)
+          end
+        end
+        if id.nil? then
+          # return as list
+          return json.values.first.map { |j| new(j) }
+        end
+        return nil if json.values.empty?
+        return new(json.values.first)
+      end
+
+      def list
+        find()
+      end
+
+    end
+    
+    def files
+      @files ||= {}
+    end
+    
+    def add_file(name, file)
+      if file.kind_of? String then
+        raise IOError.new("File not found: #{file}") if not File.exists? file
+        file = File.new(file)
+      elsif file.is_a? Tempfile
+        file = File.new(file.path)
+      end
+      return if not file.kind_of? File
+      self.files[name] = file
+    end
+    
+    def initialize(*args)
+      if args.kind_of? Hash then
+        h = args
+      elsif args.kind_of? Array and args.first.kind_of? Hash then
+        h = args.first
+      end
+      set_values(h) if h
+      self.errors = []
+    end
+
+    def set_values(h)
+      h.each_pair do |name, value|
+        writer_method = "#{name}="
+        value = parse_value(name, value)
+        if respond_to?(writer_method)
+          send(writer_method, value)
+        else
+          self[name.to_s] = value
+        end
+      end
+    end
+
+    def parse_value(name, value)
+      if !value.nil? then
+        if delimited_fields.include?(name.to_sym) then
+          value = value.split(delimited_fields[name.to_sym]) if value.is_a?(String)
+          value = value.map(&:to_i) if value.first.is_a?(String) && value.all?{ |v| v.to_i.to_s == v }
+        else
+          value = value.to_i if value.is_a?(String) && value.to_i.to_s == value
+        end
+        value
+      end
+    end
+    
+    def id_val
+      self.send(id_field)
+    end
+    
+    def id_val=(val)
+      self.send("#{id_field.to_s}=", val)
+    end
+    
+    def new_record?
+      self.new?
+    end
+
+    def new?
+      self.id_val.nil?
+    end
+
+    def [](name)
+      begin
+        send(name)
+      rescue NoMethodError
+        nil
+      end
+    end
+
+    def []=(name, value)
+      begin
+        send("#{name}=", value)
+      rescue NoMethodError
+        self.class.add_field(name)
+        send("#{name}=", value)
+      end
+    end
+    
+    def to_h
+      h = {}
+      fields.each do |f|
+        val = self.send(f)
+        h[f] = val && delimited_fields.include?(f) ? val.join(delimited_fields[f]) : val
+      end
+      h
+    end
+    
+    def to_json
+      JSON.generate(to_h())
+    end
+    
+    def to_s
+      to_json()
+    end
+
+    def update_attributes(attributes = {})
+      attributes.each_pair do |field, value|
+        send("#{field}=", value)
+      end
+      save
+    end
+
+    def save
+      begin
+        save!
+      rescue Rested::Error => e
+        self.errors = e.validations
+        false
+      end
+    end
+    
+    def save!(params = nil)
+      self.class.before_filters.each do |f| 
+        f.call(self) 
+      end 
+      uri = self.endpoint
+      uri += "/#{self.id_val}" unless new?
+      params = to_h() if not params
+      params.delete(self.id_field) if new?
+      unless self.files.empty?
+        params.merge!(self.files)
+        @files = {}
+      end
+      ret = self.post(uri, params)
+      if new? then
+        self.id_val = self.class.new(ret.values.first).id_val
+      end
+      self.class.after_filters.each do |f| 
+        f.call(self) 
+      end 
+      true
+    end
+    
+    def delete!
+      return if new?
+      uri = self.endpoint + "/#{self.id_val}"
+      self.delete(uri)
+      true
+    end
+
+    def fields
+      @fields ||= self.class.fields
+    end
+
+    def delimited_fields
+      @delimited_fields ||= self.class.delimited_fields
+    end
+  end
+end

data/lib/rested/error.rb

@@ -0,0 +1,57 @@
+
+module Rested
+    
+    class Error < ::Exception
+
+        attr_accessor :status, :reason, :http_response, :message, :validations
+
+        def initialize(res)
+
+            hash = Rested::Base.decode_response(res)
+            if hash.include? "error" then
+                self.message = hash["error"]
+            end
+            self.validations = Validations.new(hash['validations'])
+            self.status = res.status
+            self.reason = res.reason
+            self.http_response = res
+            
+        end
+        
+        def to_s
+            "#{self.status} #{self.reason}" + (self.message.nil? ? "" : ": #{self.message}")
+        end
+
+        # def self.handle(res)
+        #   case res.status
+        #       when 400
+        #           raise "Bad request"
+        #       when 401
+        #           raise "401 Unauthorized"
+        #       when 403
+        #           raise "403 Forbidden"
+        #       when 404
+        #           raise "404 Not Found"
+        #       when 405
+        #           raise "405 Method Not Allowed"
+        #       else
+        #           raise "#{res.status} #{res.reason}" if res.status >= 400
+        #   end 
+        # end
+        
+    end
+    
+    class ObjectNotFound < Error
+        attr_accessor :id
+        
+        def initialize(res)
+            super(res)
+            self.id = $1 if res.content =~ /Invalid Object.*?(\d+)/
+        end
+        
+        def to_s
+            "Invalid Object ID '#{self.id}'"
+        end
+    end
+    
+end

data/lib/rested/ext.rb

@@ -0,0 +1,97 @@
+
+# orginally cribbed from Rails edge. modified a bunch.
+
+class Hash
+  # By default, only instances of Hash itself are extractable.
+  # Subclasses of Hash may implement this method and return
+  # true to declare themselves as extractable. If a Hash
+  # is extractable, Array#extract_options! pops it from
+  # the Array when it is the last element of the Array.
+  def extractable_options?
+    instance_of?(Hash)
+  end
+end if not {}.respond_to? :extractable_options?
+
+class Array
+  # Extracts options from a set of arguments. Removes and returns the last
+  # element in the array if it's a hash, otherwise returns a blank hash.
+  #
+  #   def options(*args)
+  #     args.extract_options!
+  #   end
+  #
+  #   options(1, 2)           # => {}
+  #   options(1, 2, :a => :b) # => {:a=>:b}
+  def extract_options!
+    if last.is_a?(Hash) && last.extractable_options?
+      pop
+    else
+      {}
+    end
+  end
+end if not [].respond_to? :extract_options!
+
+# Extends the class object with class and instance accessors for attributes,
+# just like the native attr* accessors for instance attributes. Attributes can be 
+# set at the class level and overriden at the instance level as well.
+#
+#  class Person
+#    cattr_accessor :hair_colors
+#  end
+#
+#  Person.hair_colors = [:brown, :black, :blonde, :red]
+class Class
+  def rattr_reader(*syms)
+    options = syms.extract_options!
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        unless defined? @#{sym}
+          @#{sym} = nil
+        end
+
+        def self.#{sym}(#{sym} = nil)
+          return @#{sym} unless #{sym}
+          @#{sym} = #{sym} 
+        end
+      EOS
+
+      unless options[:instance_reader] == false
+        class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+          def #{sym}
+            return @#{sym} if @#{sym}
+            self.class.#{sym}
+          end
+        EOS
+      end
+    end
+  end
+
+  def rattr_writer(*syms)
+    options = syms.extract_options!
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        unless defined? @#{sym}
+          @#{sym} = nil
+        end
+
+        def self.#{sym}=(obj)
+          @#{sym} = obj
+        end
+      EOS
+
+      unless options[:instance_writer] == false
+        class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+          def #{sym}=(obj)
+            @#{sym} = obj
+          end
+        EOS
+      end
+      self.send("#{sym}=", yield) if block_given?
+    end
+  end
+
+  def rattr_accessor(*syms, &blk)
+    rattr_reader(*syms)
+    rattr_writer(*syms, &blk)
+  end
+end if not Class.respond_to? :rattr_accessor

data/lib/rested/validations.rb

@@ -0,0 +1,25 @@
+module Rested
+  class Validations
+    def initialize(validations_hash)
+      self.validations_hash = validations_hash || {}
+    end
+
+    def full_messages
+      validations_hash.inject([]) do |messages, validation|
+        messages << "#{humanize(validation.first)} #{validation.last}"
+      end
+    end
+    
+    def count
+      validations_hash.size
+    end
+
+    private
+
+    def humanize(field)
+      field.gsub(/[A-Z]/){ " #{$&.downcase}"}.capitalize
+    end
+
+    attr_accessor :validations_hash
+  end
+end

data/lib/rested.rb

@@ -0,0 +1,7 @@
+
+require File.dirname(__FILE__) + '/rested/debug'
+require File.dirname(__FILE__) + '/rested/ext'
+require File.dirname(__FILE__) + '/rested/error'
+require File.dirname(__FILE__) + '/rested/base'
+require File.dirname(__FILE__) + '/rested/entity'
+require File.dirname(__FILE__) + '/rested/validations'

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: rested
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Chetan Sarva
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-21 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httpclient
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 119
+        segments: 
+        - 2
+        - 1
+        - 5
+        - 2
+        version: 2.1.5.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 1
+        - 4
+        - 2
+        version: 1.4.2
+  type: :runtime
+  version_requirements: *id002
+description: Ruby library built on top of httpclient for working with RESTful APIs.
+email: chetan@betteradvertising.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/rested.rb
+- lib/rested/base.rb
+- lib/rested/debug.rb
+- lib/rested/entity.rb
+- lib/rested/error.rb
+- lib/rested/ext.rb
+- lib/rested/validations.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby library for working with RESTful APIs
+test_files: []
+