nimbu-api 0.0.1

data/lib/nimbu-api/pagination/page_links.rb

@@ -0,0 +1,48 @@
+module Nimbu
+  module Pagination
+    class PageLinks
+      include Nimbu::Utils::Constants
+
+      DELIM_LINKS = ",".freeze # :nodoc:
+
+      # Hold the extracted values for URI from the Link header
+      # for the first, last, next and previous page.
+      attr_accessor :first, :last, :next, :prev
+
+      # Parses links from executed request
+      #
+      def initialize(response_headers)
+        link_header = response_headers[HEADER_LINK]
+        if link_header
+          return unless link_header =~ /(next|first|last|prev)/
+
+          link_header.split(DELIM_LINKS).each do |link|
+            if link.strip =~ /<([^>]+)>; rel=\"([^\"]+)\"/
+              url_part, meta_part = $1, $2
+              next if !url_part || !meta_part
+              case meta_part
+              when META_FIRST
+                self.first = url_part
+              when META_LAST
+                self.last = url_part
+              when META_NEXT
+                self.next = url_part
+              when META_PREV
+                self.prev = url_part
+              end
+            end
+          end
+        else
+          # When on the first page
+          self.next = response_headers[HEADER_NEXT]
+          self.last = response_headers[HEADER_LAST]
+        end
+      end
+
+      def any?
+        self.first || self.last || self.next || self.prev
+      end
+
+    end # PageLinks
+  end # Pagination
+end # Nimbu

data/lib/nimbu-api/pagination/paged_request.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+module Nimbu
+  module Pagination
+    # A module that adds http get request to response pagination
+    module PagedRequest
+      include Nimbu::Utils::Constants
+
+      FIRST_PAGE = 1 # Default request page if none provided
+
+      PER_PAGE   = 30 # Default number of items as specified by API
+
+      NOT_FOUND  = -1 # Either page or per_page parameter not present
+
+      # Check if current api instance has default per_page param set,
+      # otherwise use global default.
+      #
+      def default_page_size
+        current_api.per_page ? current_api.per_page : PER_PAGE
+      end
+
+      def default_page
+        current_api.page ? current_api.page : FIRST_PAGE
+      end
+
+      # Perform http get request with paginatoin parameters
+      #
+      def page_request(path, params={})
+        if params[PARAM_PER_PAGE] == NOT_FOUND
+          params[PARAM_PER_PAGE] = default_page_size
+        end
+        if params[PARAM_PAGE] && params[PARAM_PAGE] == NOT_FOUND
+          params[PARAM_PAGE] = default_page
+        end
+
+        current_api.get_request(path, params)
+      end
+
+    end # PagedRequest
+  end # Pagination
+end # Nimbu

data/lib/nimbu-api/pagination/pagination.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+module Nimbu
+
+  # A module that decorates response with pagination helpers
+  module Pagination
+    include Nimbu::Utils::Constants
+
+    # Return page links
+    def links
+      @links = Nimbu::Pagination::PageLinks.new(env[:response_headers])
+    end
+
+    # Retrive number of total pages base on current :per_page parameter
+    def count_pages
+      page_iterator.count.to_i
+    end
+
+    # Iterate over results set pages by automatically calling `next_page`
+    # until all pages are exhausted. Caution needs to be exercised when
+    # using this feature - 100 pages iteration will perform 100 API calls.
+    # By default this is off. You can set it on the client, individual API
+    # instances or just per given request.
+    #
+    def auto_paginate(auto=false)
+      if current_api.auto_pagination? || auto
+        resources_bodies = []
+        each_page { |resource| resources_bodies += resource.body }
+        self.body = resources_bodies
+      end
+      self
+    end
+
+    # Iterator like each for response pages. If there are no pages to
+    # iterate over this method will return current page.
+    def each_page
+      yield self
+      while page_iterator.has_next?
+        yield next_page
+      end
+    end
+
+    # Retrives the result of the first page. Returns <tt>nil</tt> if there is
+    # no first page - either because you are already on the first page
+    # or there are no pages at all in the result.
+    def first_page
+      first_request = page_iterator.first
+      self.instance_eval { @env = first_request.env } if first_request
+      first_request
+    end
+
+    # Retrives the result of the next page. Returns <tt>nil</tt> if there is
+    # no next page or no pages at all.
+    def next_page
+      next_request = page_iterator.next
+      self.instance_eval { @env = next_request.env } if next_request
+      next_request
+    end
+
+    # Retrives the result of the previous page. Returns <tt>nil</tt> if there is
+    # no previous page or no pages at all.
+    def prev_page
+      prev_request = page_iterator.prev
+      self.instance_eval { @env = prev_request.env } if prev_request
+      prev_request
+    end
+    alias :previous_page :prev_page
+
+    # Retrives the result of the last page. Returns <tt>nil</tt> if there is
+    # no last page - either because you are already on the last page,
+    # there is only one page or there are no pages at all in the result.
+    def last_page
+      last_request = page_iterator.last
+      self.instance_eval { @env = last_request.env } if last_request
+      last_request
+    end
+
+    # Retrives a specific result for a page given page number.
+    # The <tt>page_number</tt> parameter is not validate, hitting a page
+    # that does not exist will return Nimbu API error. Consequently, if
+    # there is only one page, this method returns nil
+    def page(page_number)
+      request = page_iterator.get_page(page_number)
+      self.instance_eval { @env = request.env } if request
+      request
+    end
+
+    # Returns <tt>true</tt> if there is another page in the result set,
+    # otherwise <tt>false</tt>
+    def has_next_page?
+      page_iterator.has_next?
+    end
+
+    private
+
+    # Internally used page iterator
+    def page_iterator # :nodoc:
+      @page_iterator = Nimbu::Pagination::PageIterator.new(links, current_api)
+    end
+
+  end # Pagination
+end # Nimbu

data/lib/nimbu-api/request.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+
+require 'nimbu-api/request/oauth2'
+require 'nimbu-api/request/basic_auth'
+require 'nimbu-api/request/json'
+require 'nimbu-api/request/validations'
+require 'nimbu-api/request/arguments'
+
+module Nimbu
+
+  # Defines HTTP verbs
+  module Request
+    include Nimbu::Utils::Constants
+
+    METHODS = [:get, :post, :put, :delete, :patch]
+    METHODS_WITH_BODIES = [ :post, :put, :patch ]
+
+    def get_request(path, params={}, options={})
+      request(:get, path, params, options)
+    end
+
+    def patch_request(path, params={}, options={})
+      request(:patch, path, params, options)
+    end
+
+    def post_request(path, params={}, options={})
+      request(:post, path, params, options)
+    end
+
+    def put_request(path, params={}, options={})
+      request(:put, path, params, options)
+    end
+
+    def delete_request(path, params={}, options={})
+      request(:delete, path, params, options)
+    end
+
+    def request(method, path, params, options) # :nodoc:
+      if !METHODS.include?(method)
+        raise ArgumentError, "unkown http method: #{method}"
+      end
+
+      puts "EXECUTED: #{method} - #{path} with #{params} and #{options}" if ENV['DEBUG']
+
+      conn = connection(options.merge(current_options))
+      if conn.path_prefix != '/' && path.index(conn.path_prefix) != 0
+        path = (conn.path_prefix + path).gsub(/\/(\/)*/, '/')
+      end
+
+      response = conn.send(method) do |request|
+        unless options[:with_attachments]
+          case method.to_sym
+          when *(METHODS - METHODS_WITH_BODIES)
+            request.body = params.delete('data') if params.has_key?('data')
+            request.url(path, params)
+          when *METHODS_WITH_BODIES
+            request.path = path
+            request.body = extract_data_from_params(params) unless params.empty?
+          end
+        else
+          request.path = path
+          request.body = params
+        end
+      end
+      Response::Wrapper.new(response, self).auto_paginate
+    end
+
+    private
+
+    def extract_data_from_params(params) # :nodoc:
+      return params['data'] if params.has_key?('data') and !params['data'].nil?
+      return params
+    end
+
+    def _extract_mime_type(params, options) # :nodoc:
+      options['resource']  = params['resource'] ? params.delete('resource') : ''
+      options['mime_type'] = params['resource'] ? params.delete('mime_type') : ''
+    end
+
+  end # Request
+end # Nimbu

data/lib/nimbu-api/request/arguments.rb

@@ -0,0 +1,171 @@
+# encoding: utf-8
+
+require 'nimbu-api/request/normalizer'
+require 'nimbu-api/request/parameter_filter'
+
+module Nimbu
+  module Request
+    # Request arguments handler
+    class Arguments
+
+      include Normalizer
+      include ParameterFilter
+      include Validations
+
+      AUTO_PAGINATION = 'auto_pagination'.freeze
+
+      # Parameters passed to request
+      attr_reader :params
+
+      attr_reader :remaining
+
+      # The request api
+      #
+      attr_reader :api
+
+      # Required arguments
+      #
+      attr_reader :required
+      private :required
+
+      # Optional arguments
+      #
+      attr_reader :optional
+      private :optional
+
+      # Takes api, filters and required arguments
+      #
+      # = Parameters
+      #  :required - arguments that must be present before request is fired
+      #
+      def initialize(api, options={})
+        normalize! options
+        @api      = api
+        @required = options.fetch('required', []).map(&:to_s)
+        @optional = options.fetch('optional', []).map(&:to_s)
+      end
+
+      # Parse arguments to allow for flexible api calls.
+      # Arguments can be part of parameters hash or be simple string arguments.
+      #
+      def parse(*args, &block)
+        options = args.extract_options!
+        normalize! options
+
+        if !args.size.zero?
+          parse_arguments *args
+        else
+          # Arguments are inside the parameters hash
+          parse_options options
+        end
+        @params = options
+        @remaining = extract_remaining(args)
+        extract_pagination(options)
+        yield_or_eval(&block)
+        self
+      end
+
+      # Remove unkown keys from parameters hash.
+      #
+      # = Parameters
+      #  :recursive - boolean that toggles whether nested filtering should be applied
+      #
+      def sift(keys, key=nil, options={})
+        filter! keys, (key.nil? ? params : params[key]), options if keys.any?
+        self
+      end
+
+      # Check if required keys are present inside parameters hash.
+      #
+      def assert_required(required)
+        assert_required_keys required, params
+        self
+      end
+
+      # Check if parameters match expected values.
+      #
+      def assert_values(values, key=nil)
+        assert_valid_values values, (key.nil? ? params : params[key])
+        self
+      end
+
+      private
+
+      # Check and set all requried arguments.
+      #
+      def parse_arguments(*args)
+        assert_presence_of *args
+        required.each_with_index do |req, indx|
+          api.set req, args[indx]
+        end
+        check_requirement!(*args)
+      end
+
+      # Find remaining arguments
+      #
+      def extract_remaining(args)
+        args[required.size..-1]
+      end
+
+      # Fine auto_pagination parameter in options hash
+      #
+      def extract_pagination(options)
+        if (value = options.delete(AUTO_PAGINATION))
+          api.auto_pagination = value
+        end
+      end
+
+      # Remove required arguments from parameters and
+      # validate their presence(if not nil or empty string).
+      #
+      def parse_options(options)
+        options.each { |key, val| remove_required(options, key, val) }
+        provided_args = check_assignment!(options)
+        check_requirement!(*provided_args.keys)
+      end
+
+      # Remove required argument from parameters
+      #
+      def remove_required(options, key, val)
+        key = key.to_s
+        if required.include? key
+          assert_presence_of val
+          options.delete key
+          api.set key, val
+        end
+      end
+
+      # Check if required arguments have been set on instance.
+      #
+      def check_assignment!(options)
+        result = required.inject({}) { |hash, arg|
+          if api.respond_to?(:"#{arg}") && (value = api.send(:"#{arg}"))
+            hash[arg] = value
+          end
+          hash
+        }
+        assert_presence_of result
+        result
+      end
+
+      # Check if required arguments are present.
+      #
+      def check_requirement!(*args)
+        args_length     = args.length
+        required_length = required.length
+
+        if args_length < required_length
+          ::Kernel.raise ArgumentError, "wrong number of arguments (#{args_length} for #{required_length})"
+        end
+      end
+
+      # Evaluate block
+      #
+      def yield_or_eval(&block)
+        return unless block
+        block.arity > 0 ? yield(self) : self.instance_eval(&block)
+      end
+
+    end # Arguments
+  end # Request
+end # Nimbu