api_resource 0.2.1

data/lib/api_resource/callbacks.rb

@@ -0,0 +1,49 @@
+module ApiResource
+  
+  module Callbacks
+    
+    extend ActiveSupport::Concern
+    
+    included do
+      
+      extend ActiveModel::Callbacks
+      
+      define_model_callbacks :save, :create, :update, :destroy
+      
+      [:save, :create, :update, :destroy].each do |action|
+        alias_method_chain action, :callbacks
+      end
+      
+    end
+    
+    module InstanceMethods
+      
+      def save_with_callbacks(*args)
+        _run_save_callbacks do
+          save_without_callbacks(*args)
+        end
+      end
+      
+      def create_with_callbacks(*args)
+        _run_create_callbacks do
+          create_without_callbacks(*args)
+        end
+      end
+      
+      def update_with_callbacks(*args)
+        _run_update_callbacks do
+          update_without_callbacks(*args)
+        end
+      end
+      
+      def destroy_with_callbacks(*args)
+        _run_destroy_callbacks do
+          destroy_without_callbacks(*args)
+        end
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/api_resource/connection.rb

@@ -0,0 +1,171 @@
+require 'active_support/core_ext/benchmark'
+require 'rest_client'
+require 'net/https'
+require 'date'
+require 'time'
+require 'uri'
+
+module ApiResource
+  # Class to handle connections to remote web services.
+  # This class is used by ActiveResource::Base to interface with REST
+  # services.
+  class Connection
+
+    HTTP_FORMAT_HEADER_NAMES = {  
+      :get => 'Accept',
+      :put => 'Content-Type',
+      :post => 'Content-Type',
+      :delete => 'Accept',
+      :head => 'Accept'
+    }
+
+    attr_reader :site, :user, :password, :auth_type, :timeout, :proxy, :ssl_options
+    attr_accessor :format
+
+    class << self
+      def requests
+        @@requests ||= []
+      end
+    end
+
+    # The +site+ parameter is required and will set the +site+
+    # attribute to the URI for the remote resource service.
+    def initialize(site, format = ApiResource::Formats::JsonFormat)
+      raise ArgumentError, 'Missing site URI' unless site
+      @user = @password = nil
+      @uri_parser = URI.const_defined?(:Parser) ? URI::Parser.new : URI
+      self.site = site
+      self.format = format
+    end
+
+    # Set URI for remote service.
+    def site=(site)
+      @site = site.is_a?(URI) ? site : @uri_parser.parse(site)
+      @user = @uri_parser.unescape(@site.user) if @site.user
+      @password = @uri_parser.unescape(@site.password) if @site.password
+    end
+
+    # Sets the number of seconds after which HTTP requests to the remote service should time out.
+    def timeout=(timeout)
+      @timeout = timeout
+    end
+    
+    def get(path, headers = {})
+      format.decode(request(:get, path, build_request_headers(headers, :get, self.site.merge(path))))
+    end
+    
+    def delete(path, headers = {})
+      request(:delete, path, build_request_headers(headers, :delete, self.site.merge(path)))
+      return true
+    end
+    
+    def head(path, headers = {})
+      request(:head, path, build_request_headers(headers, :head, self.site.merge(path)))
+    end
+    
+    
+    def put(path, body = {}, headers = {})
+      # If there's a file to send then we can't use JSON or XML
+      if !body.is_a?(String) && RestClient::Payload.has_file?(body)
+        format.decode(request(:put, path, body, build_request_headers(headers, :put, self.site.merge(path))))
+      else
+        format.decode(request(:put, path, body, build_request_headers(headers, :put, self.site.merge(path))))
+      end
+    end
+    
+    def post(path, body = {}, headers = {})
+      if !body.is_a?(String) && RestClient::Payload.has_file?(body)
+        format.decode(request(:post, path, body, build_request_headers(headers, :post, self.site.merge(path))))
+      else
+        format.decode(request(:post, path, body, build_request_headers(headers, :post, self.site.merge(path))))
+      end
+    end
+
+
+    private
+      # Makes a request to the remote service.
+      def request(method, path, *arguments)
+        handle_response(path) do
+          ActiveSupport::Notifications.instrument("request.api_resource") do |payload|
+            
+            # debug logging
+            ApiResource.logger.debug("#{method.to_s.upcase} #{path}")
+            
+            payload[:method]      = method
+            payload[:request_uri] = "#{site.scheme}://#{site.host}:#{site.port}#{path}"
+            payload[:result]      = http(path).send(method, *arguments)
+          end
+        end
+      end
+
+      # Handles response and error codes from the remote service.
+      def handle_response(path, &block)
+        begin
+          result = yield
+        rescue RestClient::RequestTimeout
+          raise ApiResource::RequestTimeout.new("Request Time Out - Accessing #{path}}")
+        rescue Exception => error
+          if error.respond_to?(:http_code)
+            ApiResource.logger.error("#{self} accessing #{path}")
+            ApiResource.logger.error(error.message)
+            result = error.response
+          else
+            raise ApiResource::ConnectionError.new(nil, :message => "Unknown error #{error}")
+          end
+        end
+        return propogate_response_or_error(result, result.code)
+      end
+      
+      def propogate_response_or_error(response, code)
+        case code.to_i
+          when 301,302
+            raise ApiResource::Redirection.new(response)
+          when 200..400
+            response.body
+          when 400
+            raise ApiResource::BadRequest.new(response)
+          when 401
+            raise ApiResource::UnauthorizedAccess.new(response)
+          when 403
+            raise ApiResource::ForbiddenAccess.new(response)
+          when 404
+            raise ApiResource::ResourceNotFound.new(response)
+          when 405
+            raise ApiResource::MethodNotAllowed.new(response)
+          when 406
+            raise ApiResource::NotAccepatable.new(response)
+          when 409
+            raise ApiResource::ResourceNotFound.new(response)
+          when 410
+            raise ApiResource::ResourceGone.new(response)
+          when 422
+            raise ApiResource::UnprocessableEntity.new(response)
+          when 401..500
+            raise ApiResource::ClientError.new(response)
+          when 500..600
+            raise ApiResource::ServerError.new(response)
+          else
+            raise ApiResource::ConnectionError.new(response, :message => "Unknown response code: #{code}")
+        end
+      end
+      
+      # Creates new Net::HTTP instance for communication with the
+      # remote service and resources.
+      def http(path)
+        unless path =~ /\./
+          path += ".#{self.format.extension}"
+        end
+        RestClient::Resource.new("#{site.scheme}://#{site.host}:#{site.port}#{path}", {:timeout => ApiResource.timeout, :open_timeout => ApiResource.open_timeout})
+      end
+      
+      def build_request_headers(headers, verb, uri)
+        http_format_header(verb).update(headers)
+      end
+      
+      def http_format_header(verb)
+        {}.tap do |ret|
+          ret[HTTP_FORMAT_HEADER_NAMES[verb]] = format.mime_type
+        end
+      end
+  end
+end

data/lib/api_resource/core_extensions.rb

@@ -0,0 +1,7 @@
+class Array
+  
+  def symbolize_array
+    self.collect{|item| item.to_s.to_sym}
+  end
+  
+end

data/lib/api_resource/custom_methods.rb

@@ -0,0 +1,119 @@
+require 'active_support/core_ext/object/blank'
+
+module ApiResource
+  # A module to support custom REST methods and sub-resources, allowing you to break out
+  # of the "default" REST methods with your own custom resource requests.  For example,
+  # say you use Rails to expose a REST service and configure your routes with:
+  #
+  #    map.resources :people, :new => { :register => :post },
+  #                           :member => { :promote => :put, :deactivate => :delete }
+  #                           :collection => { :active => :get }
+  #
+  #  This route set creates routes for the following HTTP requests:
+  #
+  #    POST    /people/new/register.xml # PeopleController.register
+  #    PUT     /people/1/promote.xml    # PeopleController.promote with :id => 1
+  #    DELETE  /people/1/deactivate.xml # PeopleController.deactivate with :id => 1
+  #    GET     /people/active.xml       # PeopleController.active
+  #
+  # Using this module, Active Resource can use these custom REST methods just like the
+  # standard methods.
+  #
+  #   class Person < ActiveResource::Base
+  #     self.site = "http://37s.sunrise.i:3000"
+  #   end
+  #
+  #   Person.new(:name => 'Ryan).post(:register)  # POST /people/new/register.xml
+  #   # => { :id => 1, :name => 'Ryan' }
+  #
+  #   Person.find(1).put(:promote, :position => 'Manager') # PUT /people/1/promote.xml
+  #   Person.find(1).delete(:deactivate) # DELETE /people/1/deactivate.xml
+  #
+  #   Person.get(:active)  # GET /people/active.xml
+  #   # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}]
+  #
+  module CustomMethods
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        alias :orig_delete :delete
+
+        # Invokes a GET to a given custom REST method. For example:
+        #
+        #   Person.get(:active)  # GET /people/active.xml
+        #   # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}]
+        #
+        #   Person.get(:active, :awesome => true)  # GET /people/active.xml?awesome=true
+        #   # => [{:id => 1, :name => 'Ryan'}]
+        #
+        # Note: the objects returned from this method are not automatically converted
+        # into ActiveResource::Base instances - they are ordinary Hashes. If you are expecting
+        # ActiveResource::Base instances, use the <tt>find</tt> class method with the
+        # <tt>:from</tt> option. For example:
+        #
+        #   Person.find(:all, :from => :active)
+        def get(custom_method_name, options = {})
+          connection.get(custom_method_collection_url(custom_method_name, options), headers)
+        end
+
+        def post(custom_method_name, options = {}, body = '')
+          connection.post(custom_method_collection_url(custom_method_name, options), body, headers)
+        end
+
+        def put(custom_method_name, options = {}, body = '')
+          connection.put(custom_method_collection_url(custom_method_name, options), body, headers)
+        end
+
+        def delete(custom_method_name, options = {})
+          # Need to jump through some hoops to retain the original class 'delete' method
+          if custom_method_name.is_a?(Symbol)
+            connection.delete(custom_method_collection_url(custom_method_name, options), headers)
+          else
+            orig_delete(custom_method_name, options)
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      def custom_method_collection_url(method_name, options = {})
+        prefix_options, query_options = split_options(options)
+        "#{prefix(prefix_options)}#{collection_name}/#{method_name}.#{format.extension}#{query_string(query_options)}"
+      end
+    end
+
+    module InstanceMethods
+      def get(method_name, options = {})
+        connection.get(custom_method_element_url(method_name, options), self.class.headers)
+      end
+
+      def post(method_name, options = {}, body = nil)
+        request_body = body.blank? ? encode : body
+        if new?
+          connection.post(custom_method_new_element_url(method_name, options), request_body, self.class.headers)
+        else
+          connection.post(custom_method_element_url(method_name, options), request_body, self.class.headers)
+        end
+      end
+
+      def put(method_name, options = {}, body = '')
+        connection.put(custom_method_element_url(method_name, options), body, self.class.headers)
+      end
+
+      def delete(method_name, options = {})
+        connection.delete(custom_method_element_url(method_name, options), self.class.headers)
+      end
+
+
+      private
+        def custom_method_element_url(method_name, options = {})
+          "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/#{id}/#{method_name}.#{self.class.format.extension}#{self.class.__send__(:query_string, options)}"
+        end
+
+        def custom_method_new_element_url(method_name, options = {})
+          "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/new/#{method_name}.#{self.class.format.extension}#{self.class.__send__(:query_string, options)}"
+        end
+    end
+  end
+end

data/lib/api_resource/exceptions.rb

@@ -0,0 +1,87 @@
+module ApiResource
+  class ConnectionError < StandardError # :nodoc:
+    
+    cattr_accessor :http_code
+    
+    attr_reader :response
+
+    def initialize(response, options = {})
+      @response = response
+      @message  = options[:message]
+      @path     = options[:path]
+    end
+
+    def to_s
+      message = "Failed."
+      message << "  Response code = #{response.code}." if response.respond_to?(:code)
+      message << "  Response message = #{response.message}." if response.respond_to?(:message)
+      message << "\n#{@message}"
+      message << "\n#{@path}"
+    end
+    
+    def http_code
+      self.class.http_code
+    end
+    
+  end
+
+  # Raised when a Timeout::Error occurs.
+  class RequestTimeout < ConnectionError
+    def initialize(message)
+      @message = message
+    end
+    def to_s; @message ;end
+  end
+
+  # Raised when a OpenSSL::SSL::SSLError occurs.
+  class SSLError < ConnectionError
+    def initialize(message)
+      @message = message
+    end
+    def to_s; @message ;end
+  end
+
+  # 3xx Redirection
+  class Redirection < ConnectionError # :nodoc:
+    def to_s; response['Location'] ? "#{super} => #{response['Location']}" : super; end
+  end
+
+  # 4xx Client Error
+  class ClientError < ConnectionError; end # :nodoc:
+
+  # 400 Bad Request
+  class BadRequest < ClientError; self.http_code = 400; end # :nodoc
+
+  # 401 Unauthorized
+  class UnauthorizedAccess < ClientError; self.http_code = 401; end # :nodoc
+
+  # 403 Forbidden
+  class ForbiddenAccess < ClientError; self.http_code = 403; end # :nodoc
+
+  # 404 Not Found
+  class ResourceNotFound < ClientError; self.http_code = 404; end # :nodoc:
+  
+  # 406 Not Acceptable
+  class NotAcceptable < ClientError; self.http_code = 406; end
+
+  # 409 Conflict
+  class ResourceConflict < ClientError; self.http_code = 409; end # :nodoc:
+
+  # 410 Gone
+  class ResourceGone < ClientError; self.http_code = 410; end # :nodoc:
+  
+  class UnprocessableEntity < ClientError; self.http_code = 422; end
+
+  # 5xx Server Error
+  class ServerError < ConnectionError;  self.http_code = 400; end # :nodoc:
+
+  # 405 Method Not Allowed
+  class MethodNotAllowed < ClientError # :nodoc:
+    
+    self.http_code = 405
+    
+    def allowed_methods
+      @response['Allow'].split(',').map { |verb| verb.strip.downcase.to_sym }
+    end
+  end
+end

data/lib/api_resource/formats.rb

@@ -0,0 +1,14 @@
+module ApiResource
+  module Formats
+    autoload :XmlFormat, 'api_resource/formats/xml_format'
+    autoload :JsonFormat, 'api_resource/formats/json_format'
+
+    # Lookup the format class from a mime type reference symbol. Example:
+    #
+    #   ActiveResource::Formats[:xml]  # => ActiveResource::Formats::XmlFormat
+    #   ActiveResource::Formats[:json] # => ActiveResource::Formats::JsonFormat
+    def self.[](mime_type_reference)
+      ApiResource::Formats.const_get(ActiveSupport::Inflector.camelize(mime_type_reference.to_s) + "Format")
+    end
+  end
+end