api_smith 1.0.0

data/lib/api_smith.rb

@@ -0,0 +1,16 @@
+# Provides a simple set of tools built on top of Hashie and HTTParty to make
+# it easier to build clients for different apis.
+
+# @see APISmith::Smash
+# @see APISmith::Base
+#
+# @author Darcy Laycock
+# @author Steve Webb
+module APISmith
+
+  require 'api_smith/version'
+  require 'api_smith/smash'
+  require 'api_smith/client'
+  require 'api_smith/base'
+
+end

data/lib/api_smith/base.rb

@@ -0,0 +1,19 @@
+require 'api_smith/client'
+
+module APISmith
+  # A base class for building api clients (with a specified endpoint and general
+  # shared options) on top of HTTParty, including response unpacking and transformation.
+  #
+  # Used to convert APISmith::Client to a class (versus a mixin), making it useable
+  # in certain other situations where it isn't necessarily useful otherwise.
+  #
+  # @author Darcy Laycock
+  # @author Steve Webb
+  class Base
+    include APISmith::Client
+
+    def initialize(*)
+    end
+
+  end
+end

data/lib/api_smith/client.rb

@@ -0,0 +1,319 @@
+require 'httparty'
+
+module APISmith
+  # A mixin providing the base set of functionality for building API clients.
+  #
+  # @see InstanceMethods
+  # @see ClassMethods
+  # @see HTTParty
+  #
+  # @author Darcy Laycock
+  # @author Steve Webb
+  module Client
+
+    # Hooks into the mixin process to add HTTParty and the two APISmith::Client
+    # components to the given parent automatically.
+    # @param [Class] parent the object this is being mixed into
+    def self.included(parent)
+      parent.class_eval do
+        include HTTParty
+        include InstanceMethods
+        extend  ClassMethods
+      end
+    end
+
+    # The most important part of the client functionality - namely, provides a set of tools
+    # and methods that make it possible to build API clients. This is where the bulk of the
+    # client work takes place.
+    module InstanceMethods
+
+      # Given a path relative to the endpoint (or `/`), will perform a GET request.
+      #
+      # If provided, will use a `:transformer` to convert the resultant data into
+      # a useable object. Also, in the case an object is nested, allows you to
+      # traverse an object.
+      #
+      # @param [String] path the relative path to the object, pre-normalisation
+      # @param [Hash] options the raw options to be passed to ``#request!``
+      # @see #request!
+      def get(path, options = {})
+        request! :get, path, options, :query
+      end
+
+      # Given a path relative to the endpoint (or `/`), will perform a POST request.
+      #
+      # If provided, will use a `:transformer` to convert the resultant data into
+      # a useable object. Also, in the case an object is nested, allows you to
+      # traverse an object.
+      #
+      # @param [String] path the relative path to the object, pre-normalisation
+      # @param [Hash] options the raw options to be passed to ``#request!``
+      # @see #request!
+      def post(path, options = {})
+        request! :post, path, options, :query, :body
+      end
+
+      # Given a path relative to the endpoint (or `/`), will perform a PUT request.
+      #
+      # If provided, will use a `:transformer` to convert the resultant data into
+      # a useable object. Also, in the case an object is nested, allows you to
+      # traverse an object.
+      #
+      # @param [String] path the relative path to the object, pre-normalisation
+      # @param [Hash] options the raw options to be passed to ``#request!``
+      # @see #request!
+      def put(path, options = {})
+        request! :put, path, options, :query, :body
+      end
+
+      # Given a path relative to the endpoint (or `/`), will perform a DELETE request.
+      #
+      # If provided, will use a `:transformer` to convert the resultant data into
+      # a useable object. Also, in the case an object is nested, allows you to
+      # traverse an object.
+      #
+      # @param [String] path the relative path to the object, pre-normalisation
+      # @param [Hash] options the raw options to be passed to ``#request!``
+      # @see #request!
+      def delete(path, options = {})
+        request! :delete, path, options, :query
+      end
+
+      # Performs a HTTP request using HTTParty, using a set of expanded options built up by the current client.
+      #
+      # @param [:get, :post, :put, :delete] method the http request method to use
+      # @param [String] path the request path, relative to either the endpoint or /.
+      # @param [Hash{Symbol => Object}] options the options for the given request.
+      # @param [Array<Symbol>] param_types the given parameter types (e.g. :body, :query) to add to the request
+      #
+      # @option options [true,false] :skip_endpoint If true, don't expand the given path before processing.
+      # @option options [Array] :response_container If present, it will traverse an array of objects to unpack
+      # @option options [Hash] :extra_request Extra raw, request options to pass in to the request
+      # @option options [Hash] :extra_body Any parameters to add to the request body
+      # @option options [Hash] :extra_query Any parameters to add to the request query string
+      # @option options [#call] :transform An object, invoked via #call, that takes the response and
+      #   transformers it into a useable form.
+      #
+      # @return the response, defaults to the raw HTTParty::Response
+      #
+      # @see #path_for
+      # @see #extract_response
+      # @see #transform_response
+      def request!(method, path, options, *param_types)
+        # Merge in the default request options, e.g. those to be passed to HTTParty raw
+        request_options = merged_options_for(:request, options)
+        # Exapdn the path out into a full version when the endpoint is present.
+        full_path = request_options[:skip_endpoint] ? path : path_for(path)
+        # For each of the given param_types (e.g. :query, :body) will automatically
+        # merge in the options for the current request.
+        param_types.each do |type|
+          request_options[type] = merged_options_for(type, options)
+        end
+        # Finally, use HTTParty to get the response
+        response = self.class.send method, full_path, request_options
+        # Pre-process the response to check for errors.
+        check_response_errors response
+        # Unpack the response using the :response_container option
+        inner_response = extract_response path, response, options
+        # Finally, apply any transformations
+        transform_response inner_response, options
+      end
+
+      private
+
+      # Provides a hook to handle checking errors on API responses. This is called
+      # post-fetch and pre-unpacking / transformation. It is passed the apis response
+      # post-decoding (meaning JSON etc have been parsed into normal ruby objects).
+      # @param [Object] response the raw decoded api response
+      def check_response_errors(response)
+      end
+
+      # Merges in options of a given type into the base options, taking into account
+      #
+      # * Shared options (e.g. #base_query_options)
+      # * Instance-level options (e.g. #query_options)
+      # * Call-level options (e.g. the :extra_query option)
+      #
+      # @param [Symbol] type the type of options, one of :body, :query or :request
+      # @param [Hash] options the hash to check for the `:extra_{type}` option.
+      # @return [Hash] a hash of the merged options.
+      def merged_options_for(type, options)
+        base = send :"base_#{type}_options"
+        base.merge!(send(:"#{type}_options") || {})
+        base.merge! options.fetch(:"extra_#{type}", {})
+        base
+      end
+
+      # The base set of body parameters, common to all instances of the client.
+      # Ideally, in your client you'd override this to return other required
+      # parameters that are the same across all client subclasses e.g. the format.
+      #
+      # These will automatically be included in POST and PUT requests but not
+      # GET or DELETE requests.
+      #
+      # @example
+      #   def base_body_options
+      #     {:format => 'json'}
+      #   end
+      #
+      def base_body_options
+        {}
+      end
+
+      # The base set of query parameters, common to all instances of the client.
+      # Ideally, in your client you'd override this to return other required
+      # parameters that are the same across all client subclasses e.g. the format.
+      #
+      # These will automatically be included in all requests as part of the query
+      # string.
+      #
+      # @example
+      #   def base_query_options
+      #     {:format => 'json'}
+      #   end
+      #
+      def base_query_options
+        {}
+      end
+
+      # The base set of request options as accepted by HTTParty. These can be used to
+      # setup things like the normaliser HTTParty will use for parameters.
+      def base_request_options
+        {}
+      end
+
+      # Per-instance configurable query parameters.
+      # @return [Hash] the instance-specific query parameters.
+      # @see #add_query_options!
+      def query_options
+        @query_options ||= {}
+      end
+
+      # Per-instance configurable body parameters.
+      # @return [Hash] the instance-specific body parameters.
+      # @see #add_body_options!
+      def body_options
+        @body_options ||= {}
+      end
+
+      # Per-instance configurable request options.
+      # @return [Hash] the instance-specific request options.
+      # @see #add_request_options!
+      def request_options
+        @request_options ||= {}
+      end
+
+      # Merges in a hash of extra query parameters to the given request, applying
+      # them for every request that has query string parameters. Typically
+      # called from inside #initialize.
+      # @param [Hash{Symbol => Object}] value a hash of options to add recently
+      def add_query_options!(value)
+        query_options.merge! value
+      end
+
+      # Merges in a hash of extra body parameters to the given request, applying
+      # them for every request that has body parameters. Typically called from
+      # inside #initialize.
+      # @param [Hash{Symbol => Object}] value a hash of options to add recently
+      def add_body_options!(value)
+        body_options.merge! value
+      end
+
+      # Merges in a hash of request options to the given request, applying
+      # them for every request that has query string parameters. Typically called
+      # from inside #initialize.
+      # @param [Hash{Symbol => Object}] value a hash of options to add recently
+      def add_request_options!(value)
+        request_options.merge! value
+      end
+
+      # Given a path, expands it relative to the / and the defined endpoint
+      # for this class.
+      # @param [String] path the current, unexpanded path for the api call.
+      # @example With an endpoint of v1
+      #   path_for('test') # => "/v1/test"
+      def path_for(path)
+        File.join(*['', endpoint, path].compact)
+      end
+
+      # Given a path, response and options, will walk the response object
+      # (typically hashes and arrays) to unpack / extract the users response.
+      #
+      # Note that the response container will be found either via a :response_container
+      # option or, if not specified at all, the result of #default_response_container to
+      # 'get' the part of the response that the user cares about.
+      #
+      # @param [String] path the path used for the request#
+      # @param [Hash, Array] response the object returned from the api call
+      # @param [Hash] options the options passed to the api call
+      # @option options [Array<Symbol, String, Integer>] :response_container the container to unpack
+      #   from, e.g. ["a", 1, "b"], %w(a 2 3) or something else.
+      def extract_response(path, response, options)
+        # First, get the response container options
+        response_container = options.fetch(:response_container) do
+          default_response_container(path, options)
+        end
+        # And then unpack then
+        if response_container
+          response_keys = Array(response_container)
+          response = response_keys.inject(response) do |r, key|
+            r.respond_to?(:[]) ? r[key] : r
+          end
+        end
+        response
+      end
+
+      # Takes a response and, if present, uses the :transform option to convert
+      # it into a useable object.
+      # @param [Hash, Array] response the object returned from the api call
+      # @param [Hash] options the options passed to the api call
+      # @option options [#call] :transform If present, passed the unpack response.
+      # @option option [#call] :transformer see the :transform option
+      # @return [Object] the transformed response, or the response itself if no :transform
+      #   option is passed.
+      def transform_response(response, options)
+        transformer = options[:transform] || options[:transformer]
+        if transformer
+          transformer.call response
+        else
+          response
+        end
+      end
+
+      # Returns the current api endpoint, if present.
+      # @return [nil, String] the current endpoint
+      def endpoint
+        nil
+      end
+
+      # A hook method to define the default response container for a given
+      # path and set of options to an API call. Intended to be used inside
+      # subclasses to make it possible to define a standardised way to unpack
+      # responses without having to pass a `:response_container` option.
+      # @param [String] path the current path to the request
+      # @param [Hash] options the set of options passed to #request!
+      # @return [nil, Array] the array of indices (either hash / array indices)
+      #   to unpack the response via.
+      def default_response_container(path, options)
+        nil
+      end
+
+    end
+
+    # Class level methods to let you configure your api client.
+    module ClassMethods
+
+      # When present, lets you specify the api for the given client.
+      # @param [String, nil] value the endpoint to use.
+      # @example Setting a string endpoint
+      #   endpoint 'v1'
+      # @example Unsetting the string endpoint
+      #   endpoint nil
+      def endpoint(value = nil)
+        define_method(:endpoint) { value }
+      end
+
+    end
+
+  end
+end

data/lib/api_smith/smash.rb

@@ -0,0 +1,212 @@
+require 'hashie/dash'
+
+module APISmith
+  # Extends Hashie::Dash to suppress unknown keys when passing data, but
+  # is configurable to raises an UnknownKey exception when accessing keys in the
+  # Smash.
+  #
+  # APISmith::Smash is a subclass of Hashie::Dash that adds several features
+  # making it suitable for use in writing api clients. Namely,
+  #
+  # * The ability to silence exceptions on unknown keys (vs. Raising NoMethodError)
+  # * The ability to define conversion of incoming data via transformers
+  # * The ability to define aliases for keys via the from parameter.
+  #
+  # @author Darcy Laycock
+  # @author Steve Webb
+  #
+  # @example a simple, structured object with the most common use cases.
+  #   class MyResponse < APISmith::Smash
+  #     property :full_name, :from => :fullName
+  #     property :value_percentage, :transformer => :to_f
+  #     property :short_name
+  #     property :created, :transformer => lambda { |v| Date.parse(v) }
+  #   end
+  #
+  #   response = MyResponse.new({
+  #     :fullName         => "Bob Smith",
+  #     :value_percentage => "10.5",
+  #     :short_name       => 'Bob',
+  #     :created          => '2010-12-28'
+  #   })
+  #
+  #   p response.short_name # => "Bob"
+  #   p response.full_name # => "Bob Smith"
+  #   p response.value_percentage # => 10.5
+  #   p response.created.class # => Date
+  #
+  class Smash < Hashie::Dash
+    # When we access an unknown property, we raise the unknown key instead of
+    # a NoMethodError on undefined keys so that we can do a target rescue.
+    class UnknownKey < StandardError; end
+
+    # Returns a class-specific hash of transformers, containing the attribute
+    # name mapped to the transformer that responds to call.
+    # @return The hash of transformers.
+    def self.transformers
+      (@transformers ||= {})
+    end
+
+    # Returns a class-specific hash of incoming keys and their resultant
+    # property name, useful for mapping non-standard names (e.g. displayName)
+    # to their more ruby-like equivelant (e.g. display_name).
+    # @return The hash of key mappings.
+    def self.key_mapping
+      (@key_mapping ||= {})
+    end
+
+    # Test if the object should raise a NoMethodError exception on unknown
+    # property accessors or whether it should be silenced.
+    #
+    # @return true if an exception will be raised when accessing an unknown key
+    #   else, false.
+    def self.exception_on_unknown_key?
+      defined?(@exception_on_unknown_key) && @exception_on_unknown_key
+    end
+
+    # Sets whether or not Smash should raise NoMethodError on an unknown key.
+    # Sets it for the current class.
+    #
+    # @param [Boolean] value true to throw exceptions.
+    def self.exception_on_unknown_key=(value)
+      @exception_on_unknown_key = value
+    end
+    self.exception_on_unknown_key = false
+
+    # Sets the transformer that is invoked when the given key is set.
+    #
+    # @param [Symbol] key The key should this transformer operate on
+    # @param [#call] value If a block isn't given, used to transform via #call.
+    # @param [Block] blk The block used to transform the key.
+    def self.transformer_for(key, value = nil, &blk)
+      if blk.nil? && value
+        blk = value.respond_to?(:call) ? value : value.to_sym.to_proc
+      end
+      raise ArgumentError, 'must provide a transformation' if blk.nil?
+      transformers[key.to_s] = blk
+      # For each subclass, set the transformer.
+      Array(@subclasses).each { |klass| klass.transformer_for(key, value) }
+    end
+
+    # Hook to make it inherit instance variables correctly. Called once
+    # the Smash is inherited from in another object to maintain state.
+    def self.inherited(klass)
+      super
+      klass.instance_variable_set '@transformers',             transformers.dup
+      klass.instance_variable_set '@key_mapping',              key_mapping.dup
+      klass.instance_variable_set '@exception_on_unknown_key', exception_on_unknown_key?
+    end
+
+    # Create a new property (i.e., hash key) for this Object type. This method
+    # allows for converting property names and defining custom transformers for
+    # more complex types.
+    #
+    # @param [Symbol] property_name The property name (duh).
+    # @param [Hash] options
+    # @option options [String, Array<String>] :from Also accept values for this property when
+    #   using the key(s) specified in from.
+    # @option options [Block] :transformer Specify a class or block to use when transforming the data.
+    def self.property(property_name, options = {})
+      super
+      if options[:from]
+        property_name = property_name.to_s
+        Array(options[:from]).each do |k|
+          key_mapping[k.to_s] = property_name
+        end
+      end
+      if options[:transformer]
+        transformer_for property_name, options[:transformer]
+      end
+    end
+
+    # Does this Smash class contain a specific property (key),
+    # or does it have a key mapping (via :from)
+    #
+    # @param [Symbol] key the property to test for.
+    # @return [Boolean] true if this class contains the key; else, false.
+    def self.property?(key)
+      super || key_mapping.has_key?(key.to_s)
+    end
+
+    # Automates type conversion (including on Array and Hashes) to this type.
+    # Used so we can pass this class similarily to how we pass lambdas as an
+    # object, primarily for use as transformers.
+    #
+    # @param [Object] the object to attempt to convert.
+    # @return [Array<Smash>, Smash] The converted object / array of objects if
+    #   possible, otherwise nil.
+    def self.call(value)
+      if value.is_a?(Array)
+        value.map { |v| call v }.compact
+      elsif value.is_a?(Hash)
+        new value
+      else
+        nil
+      end
+    end
+
+    # Access the value responding to a key, normalising the key into a form
+    # we know (e.g. processing the from value to convert it to the actual
+    # property name).
+    #
+    # @param [Symbol] property the key to check for.
+    # @return The value corresponding to property. nil if it does not exist.
+    def [](property)
+      super transform_key(property)
+    rescue UnknownKey
+      nil
+    end
+
+    # Sets the value for a given key. Transforms the key first (e.g. taking into
+    # account from values) and transforms the property using any transformers.
+    #
+    # @param [Symbol] property the key to set.
+    # @param [String] value the value to set.
+    # @return If the property exists value is returned; else, nil.
+    def []=(property, value)
+      key = transform_key(property)
+      super key, transform_property(key, value)
+    rescue UnknownKey
+      nil
+    end
+
+    private
+
+    # Overrides the Dashie check to raise a custom exception that we can
+    # rescue from when the key is unknown.
+    def assert_property_exists!(property)
+      has_property = self.class.property?(property)
+      unless has_property
+        exception = self.class.exception_on_unknown_key? ? NoMethodError : UnknownKey
+        raise exception, "The property '#{property}' is not defined on this #{self.class.name}"
+      end
+    end
+
+    # Transforms a given key into it's normalised alternative, making it
+    # suitable for automatically mapping external objects into a useable
+    # local version.
+    # @param [Symbol, String] key the starting key, pre-transformation
+    # @return [String] the transformed key, ready for use internally.
+    def transform_key(key)
+      self.class.key_mapping[key.to_s] || default_key_transformation(key)
+    end
+
+    # By default, we transform the key using #to_s, making it useable
+    # as a hash index. If you want to, for example, add leading underscores,
+    # you're do so here.
+    def default_key_transformation(key)
+      key.to_s
+    end
+
+    # Given a key and a value, applies any incoming data transformations as appropriate.
+    # @param [String, Symbol] key the property key
+    # @param [Object] value the incoming value of the given property
+    # @return [Object] the transformed value for the given key
+    # @see Smash.transformer_for
+    def transform_property(key, value)
+      transformation = self.class.transformers[key.to_s]
+      transformation ? transformation.call(value) : value
+    end
+
+  end
+end

data/lib/api_smith/version.rb

@@ -0,0 +1,4 @@
+module APISmith
+  # The current version of API Smith
+  VERSION = "1.0.0".freeze
+end

data/lib/api_smith/web_mock_extensions.rb

@@ -0,0 +1,42 @@
+module APISmith
+  # A set of extensions to make using APISmith with WebMock (or most test utilities in general)
+  # simpler when it comes checking values. Please note this is primarily intended for use with
+  # rspec due to dependence on subject in some places.
+  #
+  # @author Darcy Laycock
+  # @author Steve Webb
+  module WebMockExtensions
+
+    # Returns the class of the current subject
+    # @return [Class] the subject class
+    def subject_api_class
+      subject.is_a?(Class) ? subject : subject.class
+    end
+
+    # Returns an instance of the subject class, created via allocate (vs. new)
+    # @return [Object] the instance
+    def subject_class_instance
+      @subject_class_instance ||= subject_api_class.allocate
+    end
+
+    # Expands the given path relative to the API for the current subject class.
+    # Namely, this makes it possible to convert a relative path to an endpoint-specified
+    # path.
+    # @param [String] path the path to expand, minus endpoint etc.
+    # @return [String] the expanded path
+    def api_url_for(path)
+      path     = subject_class_instance.send(:path_for, path)
+      base_uri = subject_api_class.base_uri
+      File.join base_uri, path
+    end
+
+    # Short hand for #stub_request that lets you give it a relative path prior to expanding it.
+    # @param [:get, :post, :put, :delete] the verb for the request
+    # @param [String] the relative path for the api
+    # @return [Object] the result from stub_request
+    def stub_api(type, path)
+      stub_request(type, api_url_for(path))
+    end
+
+  end
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification 
+name: api_smith
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Darcy Laycock
+- Steve Webb
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-21 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: hashie
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rr
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: fuubar
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: APISmith provides tools to make working with structured HTTP-based apis even easier.
+email: 
+- sutto@thefrontiergroup.com.au
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/api_smith/base.rb
+- lib/api_smith/client.rb
+- lib/api_smith/smash.rb
+- lib/api_smith/version.rb
+- lib/api_smith/web_mock_extensions.rb
+- lib/api_smith.rb
+has_rdoc: true
+homepage: http://github.com/thefrontiergroup
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A simple layer on top of HTTParty for building API's
+test_files: []
+