ohanakapa 1.0.0

data/lib/ohanakapa/client/organizations.rb

@@ -0,0 +1,43 @@
+module Ohanakapa
+  class Client
+
+    # Methods for the Organizations API
+    #
+    # @see http://ohanapi.herokuapp.com/api/docs
+    module Organizations
+
+      # List all organizations
+      #
+      # This provides a dump of every organization, in the order that they
+      # were uploaded to the Ohana DB.
+      #
+      # @see http://ohanapi.herokuapp.com/api/docs#!/api/GET-api-organizations---format-_get_0
+      #
+      # @return [Array<Sawyer::Resource>] List of Organizations.
+      #
+      # @example
+      #   Ohanakapa.organizations
+      # @example
+      #   Ohanakapa.orgs
+      def organizations
+        get "organizations"
+      end
+      alias :orgs :organizations
+
+      # Get a single organization based on its ID
+      # @see http://ohanapi.herokuapp.com/api/docs#!/api/GET-api-organizations--id---format-_get_1
+      #
+      # @param id [String] Organization ID.
+      # @return [Sawyer::Resource]
+      # @example
+      #   Ohanakapa.organization('519c44065634241897000023')
+      # @example
+      #   Ohanakapa.org('519c44065634241897000023')
+      def organization(id)
+        get("organizations/#{id}")
+      end
+      alias :org :organization
+
+    end
+  end
+end

data/lib/ohanakapa/client/rate_limit.rb

@@ -0,0 +1,34 @@
+module Ohanakapa
+  class Client
+
+    # Methods for API rate limiting info
+    #
+    # @see http://ohanapi.herokuapp.com/api/docs
+    module RateLimit
+
+      # Get rate limit info from last response if available
+      # or make a new request to fetch rate limit
+      #
+      # @see http://ohanapi.herokuapp.com/api/docs
+      # @return [Ohanakapa::RateLimit] Rate limit info
+      def rate_limit(options = {})
+        return rate_limit! if last_response.nil?
+
+        Ohanakapa::RateLimit.from_response(last_response)
+      end
+      alias ratelimit rate_limit
+
+
+      # Refresh rate limit info by making a new request
+      #
+      # @see http://ohanapi.herokuapp.com/api/docs
+      # @return [Ohanakapa::RateLimit] Rate limit info
+      def rate_limit!(options = {})
+        get "rate_limit"
+        Ohanakapa::RateLimit.from_response(last_response)
+      end
+      alias ratelimit! rate_limit!
+
+    end
+  end
+end

data/lib/ohanakapa/client/search.rb

@@ -0,0 +1,23 @@
+module Ohanakapa
+  class Client
+
+    # Methods for the Search API
+    #
+    # @see http://ohanapi.herokuapp.com/api/docs#!/api/GET-api-search---format-_get_11
+    module Search
+
+      # Performs a query of the API
+      # @param options [Hash] Search term and qualifiers
+      # @option options [String] :keyword Keyword search term
+      # @option options [String] :location Location search term
+      # @option options [Float]  :radius Distance in miles from Location
+      # @option options [String] :language Language spoken at Location
+      # @option options [Fixnum] :page Page of paginated results
+      # @return [Sawyer::Resource] Search results object
+      def search(path, options = {})
+        paginate path, options
+      end
+
+    end
+  end
+end

data/lib/ohanakapa/configurable.rb

@@ -0,0 +1,78 @@
+module Ohanakapa
+
+  # Configuration options for {Client}, defaulting to values
+  # in {Default}
+  module Configurable
+    # @!attribute api_endpoint
+    #   @return [String] Base URL for API requests. default: http://ohanapi.herokuapp.com/api/
+    # @!attribute auto_paginate
+    #   @return [Boolean] Auto fetch next page of results until rate limit reached
+    # @!attribute [w] api_token
+    #   @return [String] Configure OAuth app secret
+    # @!attribute default_media_type
+    #   @see http://developer.github.com/v3/media/
+    #   @return [String] Configure preferred media type (for API versioning, for example)
+    # @!attribute connection_options
+    #   @see https://github.com/lostisland/faraday
+    #   @return [Hash] Configure connection options for Faraday
+    # @!attribute login
+    #   @return [String] GitHub username for Basic Authentication
+    # @!attribute middleware
+    #   @see https://github.com/lostisland/faraday
+    #   @return [Faraday::Builder] Configure middleware for Faraday
+    # @!attribute per_page
+    #   @return [String] Configure page size for paginated results. API default: 30
+    # @!attribute proxy
+    #   @see https://github.com/lostisland/faraday
+    #   @return [String] URI for proxy server
+    # @!attribute user_agent
+    #   @return [String] Configure User-Agent header for requests.
+
+    attr_accessor :api_endpoint, :auto_paginate, :connection_options,
+                  :default_media_type, :middleware, :proxy,
+                  :user_agent
+    attr_writer :api_token
+
+    class << self
+
+      # List of configurable keys for {Ohanakapa::Client}
+      # @return [Array] of option keys
+      def keys
+        @keys ||= [
+          :api_endpoint,
+          :auto_paginate,
+          :api_token,
+          :connection_options,
+          :default_media_type,
+          :middleware,
+          :proxy,
+          :user_agent
+        ]
+      end
+    end
+
+    # Set configuration options using a block
+    def configure
+      yield self
+    end
+
+    # Reset configuration options to default values
+    def reset!
+      Ohanakapa::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", Ohanakapa::Default.options[key])
+      end
+      self
+    end
+    alias setup reset!
+
+    def api_endpoint
+      File.join(@api_endpoint, "")
+    end
+
+    private
+
+    def options
+      Hash[Ohanakapa::Configurable.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+    end
+  end
+end

data/lib/ohanakapa/default.rb

@@ -0,0 +1,88 @@
+require 'ohanakapa/response/raise_error'
+require 'ohanakapa/version'
+
+module Ohanakapa
+
+  # Default configuration options for {Client}
+  module Default
+
+    # Default API endpoint
+    API_ENDPOINT = "http://ohanapi.herokuapp.com/api".freeze
+
+    # Default User Agent header string
+    USER_AGENT   = "Ohanakapa Ruby Gem #{Ohanakapa::VERSION}".freeze
+
+    # Default media type
+    MEDIA_TYPE   = "application/vnd.ohanapi-v1+json"
+
+    # Default Faraday middleware stack
+    MIDDLEWARE = Faraday::Builder.new do |builder|
+      builder.use Ohanakapa::Response::RaiseError
+      builder.adapter Faraday.default_adapter
+    end
+
+    class << self
+
+      # Configuration options
+      # @return [Hash]
+      def options
+        Hash[Ohanakapa::Configurable.keys.map{|key| [key, send(key)]}]
+      end
+
+      # Default API endpoint from ENV or {API_ENDPOINT}
+      # @return [String]
+      def api_endpoint
+        ENV['OHANAKAPA_API_ENDPOINT'] || API_ENDPOINT
+      end
+
+      # Default pagination preference from ENV
+      # @return [String]
+      def auto_paginate
+        ENV['OHANAKAPA_AUTO_PAGINATE']
+      end
+
+      # Default options for Faraday::Connection
+      # @return [Hash]
+      def connection_options
+        {
+          :headers => {
+            :accept => default_media_type,
+            :user_agent => user_agent
+          }
+        }
+      end
+
+      # Default media type from ENV or {MEDIA_TYPE}
+      # @return [String]
+      def default_media_type
+        ENV['OHANAKAPA_DEFAULT_MEDIA_TYPE'] || MEDIA_TYPE
+      end
+
+      # Default middleware stack for Faraday::Connection
+      # from {MIDDLEWARE}
+      # @return [String]
+      def middleware
+        MIDDLEWARE
+      end
+
+      # Default proxy server URI for Faraday connection from ENV
+      # @return [String]
+      def proxy
+        ENV['OHANAKAPA_PROXY']
+      end
+
+      # Default api token for Ohana API
+      # @return [String]
+      def api_token
+        ENV['OHANAKAPA_API_TOKEN']
+      end
+
+      # Default User-Agent header string from ENV or {USER_AGENT}
+      # @return [String]
+      def user_agent
+        ENV['OHANAKAPA_USER_AGENT'] || USER_AGENT
+      end
+
+    end
+  end
+end

data/lib/ohanakapa/error.rb

@@ -0,0 +1,130 @@
+module Ohanakapa
+  # Custom error class for rescuing from all Ohana API errors
+  class Error < StandardError
+
+    # Returns the appropriate Ohanakapa::Error subclass based
+    # on status and response message
+    #
+    # @param [Hash] response HTTP response
+    # @return [Ohanakapa::Error]
+    def self.from_response(response)
+      status = response[:status].to_i
+      body  = response[:body].to_s
+
+      if klass =  case status
+                  when 400 then Ohanakapa::BadRequest
+                  when 401 then Ohanakapa::Unauthorized
+                  when 403
+                    if body =~ /rate limit exceeded/i
+                      Ohanakapa::TooManyRequests
+                    elsif body =~ /login attempts exceeded/i
+                      Ohanakapa::TooManyLoginAttempts
+                    else
+                      Ohanakapa::Forbidden
+                    end
+                  when 404 then Ohanakapa::NotFound
+                  when 406 then Ohanakapa::NotAcceptable
+                  #when 422 then Ohanakapa::UnprocessableEntity
+                  when 500 then Ohanakapa::InternalServerError
+                  when 501 then Ohanakapa::NotImplemented
+                  when 502 then Ohanakapa::BadGateway
+                  when 503 then Ohanakapa::ServiceUnavailable
+                  end
+        klass.new(response)
+      end
+    end
+
+    def initialize(response=nil)
+      @response = response
+      super(build_error_message)
+    end
+
+    private
+
+    def data
+      @data ||=
+        if (body = @response[:body]) && !body.empty?
+          if body.is_a?(String) &&
+            @response[:response_headers] &&
+            @response[:response_headers][:content_type] =~ /json/
+
+            Sawyer::Agent.serializer.decode(body)
+          else
+            body
+          end
+        else
+          nil
+        end
+    end
+
+    def response_message
+      case data
+      when Hash
+        data[:message] || data[:description]
+      when String
+        data
+      end
+    end
+
+    def response_error
+      "Error: #{data[:error]}" if data.is_a?(Hash) && data[:error]
+    end
+
+    def response_error_summary
+      return nil unless data.is_a?(Hash) && !Array(data[:errors]).empty?
+
+      summary = "\nError summary:\n"
+      summary << data[:errors].map do |hash|
+        hash.map { |k,v| "  #{k}: #{v}" }
+      end.join("\n")
+
+      summary
+    end
+
+    def build_error_message
+      return nil if @response.nil?
+
+      message =  "#{@response[:method].to_s.upcase} "
+      message << "#{@response[:url].to_s}: "
+      message << "#{@response[:status]} - "
+      message << "#{response_message}" unless response_message.nil?
+      message << "#{response_error}" unless response_error.nil?
+      message << "#{response_error_summary}" unless response_error_summary.nil?
+      message
+    end
+  end
+
+  # Raised when Ohana API returns a 400 HTTP status code
+  class BadRequest < Error; end
+
+  # Raised when Ohana API returns a 401 HTTP status code
+  class Unauthorized < Error; end
+
+  # Raised when Ohana API returns a 403 HTTP status code
+  class Forbidden < Error; end
+
+  # Raised when GitHub returns a 403 HTTP status code
+  # and body matches 'rate limit exceeded'
+  class TooManyRequests < Forbidden; end
+
+  # Raised when Ohana API returns a 404 HTTP status code
+  class NotFound < Error; end
+
+  # Raised when Ohana API returns a 406 HTTP status code
+  class NotAcceptable < Error; end
+
+  # Raised when Ohana API returns a 422 HTTP status code
+  class UnprocessableEntity < Error; end
+
+  # Raised when Ohana API returns a 500 HTTP status code
+  class InternalServerError < Error; end
+
+  # Raised when Ohana API returns a 501 HTTP status code
+  class NotImplemented < Error; end
+
+  # Raised when Ohana API returns a 502 HTTP status code
+  class BadGateway < Error; end
+
+  # Raised when Ohana API returns a 503 HTTP status code
+  class ServiceUnavailable < Error; end
+end

data/lib/ohanakapa/rate_limit.rb

@@ -0,0 +1,31 @@
+module Ohanakapa
+
+  # Class for API Rate Limit info
+  #
+  # @!attribute [w] limit
+  #   @return [Fixnum] Max tries per rate limit period
+  # @!attribute [w] remaining
+  #   @return [Fixnum] Remaining tries per rate limit period
+  # @!attribute [w] resets_at
+  #   @return [Time] Indicates when rate limit resets
+  # @!attribute [w] resets_in
+  #   @return [Fixnum] Number of seconds when rate limit resets
+  #
+  # @see http://ohanapi.herokuapp.com/api/docs/v1/#rate-limiting
+  class RateLimit < Struct.new :limit, :remaining
+
+    # Get rate limit info from HTTP response
+    #
+    # @param response [#headers] HTTP response
+    # @return [RateLimit]
+    def self.from_response(response)
+      info = new
+      if response && !response.headers.nil?
+        info.limit = response.headers['X-RateLimit-Limit'].to_i
+        info.remaining = response.headers['X-RateLimit-Remaining'].to_i
+      end
+
+      info
+    end
+  end
+end

data/lib/ohanakapa/response/raise_error.rb

@@ -0,0 +1,21 @@
+require 'faraday'
+require 'ohanakapa/error'
+
+module Ohanakapa
+  # Faraday response middleware
+  module Response
+
+    # This class raises an Ohanakapa-flavored exception based on
+    # HTTP status codes returned by the API
+    class RaiseError < Faraday::Response::Middleware
+
+      private
+
+      def on_complete(response)
+        if error = Ohanakapa::Error.from_response(response)
+          raise error
+        end
+      end
+    end
+  end
+end