http_api_client 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ODliNzQyOGIyOGNmOGEyYjFlZGRjNTg2MGU1MjExODdjMDIzYzg3OQ==
+  data.tar.gz: !binary |-
+    NjgxOGE3OWRjYzQ0ZmYxMGM3MjA0MWE5ZDE1YTI0ZTU5MDEwMGM0OA==
+SHA512:
+  metadata.gz: !binary |-
+    YzZiZWE4ZWFjMTllNjZjYTg4MDVkYWRmNDUwZmQzY2ViNDE0ZDRmOTkyZDQw
+    MTM1NGI2MDY1NzU5NDY5MzM3MjVmNjc5MjdjYjdhZjEyNGMyN2JlYTU1YzBl
+    Nzg1ZjAwMjY1NTYxYzQzN2ZhNzc5OGQxYzBiN2Y4ZTc3YjE4NmQ=
+  data.tar.gz: !binary |-
+    NzNiMzk1MjE2MjIwMTkxNzBmOGNmNjFlYzMxNTVhNjIwY2QxZDg1OTc2MzIw
+    NzAwMDQyOGFhZmJlZjc2YWEwZTk0OGQxMGZmYWRjMzE4MTYwZGViZWM0ZjIy
+    ZDE3NmVhY2UxYjBkOTc4ZWZhNGZhYWY5ZGFlZTVjM2IyMzZlYmE=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--profile

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in http_api_client.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Rob Monie
+
+MIT License
+
+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/README.md

@@ -0,0 +1,143 @@
+# HttpApiClient
+Basic shared http related utils and error translation for places applications.
+
+Currently:
+- Http client - faraday based, configurable, threadsafe, ssl capable.
+- Error translation. Translates http status codes to named errors for more precise error handling in application code.
+
+
+## Usage
+
+Create a http client by extending `HttpApiClient::Client` and providing a configuration key for the config relating to that client:
+
+```ruby
+module ApiClients
+  class Foursquare < HttpApiClient::Client
+
+    include Singleton
+
+    def initialize
+      super(:foursquare)
+    end
+  end
+end
+```
+
+This will construct a http client configured as 'places_api' in the `config/http_api_clients.yml` configuration file.
+
+Eg:
+```
+production:
+  foursquare:
+    protocol: https
+    server: api.foursquare.com
+    #port: 443 (not required)
+    #base_uri: '' (not required)
+
+development:
+  foursquare:
+    protocol: https
+    server: api.foursquare.com
+    #port: 443 (not required)
+    #base_uri: '' (not required)
+
+
+#etc. Regular yaml defaults / overrides etc can be used to keep DRY
+
+```
+
+### Possible keys
+
+* ```protocol```              - protocol, e.g. **https** or **http**
+* ```server```                - the host name, e.g. **api.foursquare.com**
+* ```port```                  - self-explanatory (not required)
+* ```base_uri```              - base path/uri e.g. **/api** (not required)
+* ```http_basic_username```   - username for HTTP Basic Auth (not required)
+* ```http_basic_password```   - password for HTTP Basic Auth (not required)
+* ```ca_file```               - the path to a self-signed cert authority file, e.g. **/usr/local/etc/nginx/my-server.crt** (not required)
+
+By implementing your http clients as singletons, you can make the most of faraday's persistent http connections via net_http_persistent. This can have a significant impact on performance for chatty apps assuming that the target server implements keep-alive.
+
+### Specifiying Token Authentication Params
+
+Some http apis such as foursquare or instagram require auth params to be passed. These can be defined at the client level by implementing the `auth_params` method.
+
+```ruby
+module ApiClients
+  class Foursquare < HttpApiClient::Client
+
+    include Singleton
+
+    def initialize
+      super(:foursquare)
+    end
+
+    def auth_params
+      {
+        client_id: Application.config.foursquare_client_id,
+        client_secret: Application.config.foursquare_secret,
+        v: Date.today.strftime('%Y%m%d')
+      }
+    end
+
+  end
+end
+```
+
+### Current API
+
+All api calls will return ruby hashed version of json responsea and translate error codes to appropriate Errors (Eg. 404 -> HttpApiClient::NotFound)
+
+
+#### Raw Http Api
+```ruby
+# GET
+client.get(base_path, params, headers)
+
+# POST
+client.create(base_path, payload)
+
+# DELETE
+client.destroy(base_path, id)
+
+# UPDATE  - Not yet implemented (if you need it, add it)
+
+```
+
+#### Higher level Api
+
+Not sure if this belongs here yet. It may be removed. These all just pass through to `client.get`
+
+```ruby
+# GET
+client.find(base_path, id, query = {})
+
+client.find_nested(base_path, id, nested_path)
+
+client.find_all(base_path, query = {})
+
+```
+
+#### Request Id Tracking
+In order to provide a common request id from api call to the service provider for the purposes of monitoring, a Request-Id header can be
+added to all requests. In order to do this, the following config options is required:
+
+`include_request_id_header: true`
+
+In addition to this, your client code should have set a thread local variable keyed under `request_id`.
+
+Eg: `Thread.current[:request_id] = request_id`
+
+With these in place, a request header will be added to the http request which can then be picked up and logged throughout the service provider application code.
+
+## SSL Support
+
+SSL is supported but requires certificates for the major certificate authorities to be installed when used on OSX. Linux should have these already.
+
+`brew install curl-ca-bundle`
+
+This will install `/usr/local/opt/curl-ca-bundle/share/ca-bundle.crt`
+
+## TODO:
+
+* Consider enforcing an SSL connection when using HTTP Basic Auth

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/http_api_client.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'http_api_client/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'http_api_client'
+  spec.version       = HttpApiClient::VERSION
+  spec.authors       = ['Rob Monie', 'Andrei Miulescu', 'Stuart Liston', 'Chris Rhode']
+  spec.email         = ['robmonie@gmail.com']
+  spec.description   = %q{Http client wrapper for simplified api access}
+  spec.summary       = %q{}
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+  spec.add_development_dependency 'pry', '~> 0.9'
+  spec.add_development_dependency 'pry-debugger', '~> 0.2'
+
+  spec.add_dependency 'activesupport', '>= 3.1'
+  spec.add_dependency 'faraday', '~> 0.9'
+  spec.add_dependency 'net-http-persistent', '~> 2.9'
+  spec.add_dependency 'oj', '~> 2.7'
+
+
+
+end

data/lib/http_api_client/client.rb

@@ -0,0 +1,159 @@
+# coding: utf-8
+
+require 'active_support/core_ext/object/to_query'
+require "active_support/json"
+require 'faraday'
+require 'oj'
+require 'http_api_client'
+require 'http_api_client/errors'
+require 'http_api_client/connection_factory'
+require 'http_api_client/timed_result'
+
+module HttpApiClient
+  class Client
+
+    include HttpApiClient::Errors::Factory
+
+    attr_reader :config
+
+    def initialize(client_id, config_file = nil)
+      raise "You must supply a http client config id (as defined in #{config_file || Config::DEFAULT_CONFIG_FILE_LOCATION}" unless client_id
+
+      if config_file
+        @config = Config.new(config_file).send(client_id)
+      else
+        @config = Config.new.send(client_id)
+      end
+
+    end
+
+    def find(base_path, id, query = {})
+      get("#{base_path}/#{id}", query)
+    end
+
+    def find_nested(base_path, id, nested_path)
+      get("#{base_path}/#{id}/#{nested_path}")
+    end
+
+    def find_all(base_path, query = {})
+      get("#{base_path}", query)
+    end
+
+    def get(path, query = {}, custom_headers = {})
+
+      log_data = { method: 'get', host: config.server, path: path_with_query(path, query) }
+
+      response = TimedResult.time('http_api_client_request', log_data) do
+        connection.get(full_path(path), with_auth(query), request_headers(get_headers, custom_headers))
+      end
+
+      handle_response(response, :get, path)
+    end
+
+    def create(path, payload, custom_headers = {})
+
+      log_data = { method: 'post', host: config.server, path: full_path(path) }
+
+      response = TimedResult.time('http_api_client_request', log_data) do
+        connection.post(full_path(path), JSON.fast_generate(with_auth(payload)), request_headers(update_headers, custom_headers))
+      end
+
+      handle_response(response, :post, path)
+    end
+
+    def destroy(base_path, id, custom_headers = {})
+
+      path = "#{base_path}/#{id}"
+      log_data = { method: 'delete', host: config.server, path: full_path(path) }
+
+      response = TimedResult.time('http_api_client_request', log_data) do
+        connection.delete(full_path(path), request_headers(update_headers, custom_headers))
+      end
+
+      handle_response(response, :delete, path)
+    end
+
+    def connection
+      @connection ||= ConnectionFactory.new(config).create
+    end
+
+    private
+
+    def params_encoder
+      @params_encoder ||= HttpApiClient.params_encoder
+    end
+
+    def auth_params
+      {}
+    end
+
+    def handle_response(response, method, path)
+      if ok?(response) || validation_failed?(response)
+        if response.body
+          #Don't use regular load method - any strings starting with ':' ( :-)  from example) will be interpreted as a symbol
+          Oj.strict_load(response.body)
+        else
+          true
+        end
+      else
+        error_class = error_for_status(response.status)
+        message = "#{response.status} #{method}: #{path}"
+        HttpApiClient.logger.warn("Http Client #{error_class}: #{message}")
+        raise error_class.new(message, response.body)
+      end
+    end
+
+    def ok?(response)
+      Integer(response.status).between?(200, 299)
+    end
+
+    def validation_failed?(response)
+      Integer(response.status) == 422
+    end
+
+    def full_path(path)
+      path = "/#{config.base_uri}/#{path}".gsub(/\/+/, '/')
+      path
+    end
+
+    def path_with_query(path, query)
+      path = full_path(path)
+      path += "?#{params_encoder.encode(query)}" unless query.keys.empty?
+      path
+    end
+
+    def with_auth(query)
+      query.merge(auth_params)
+    end
+
+    def request_headers(base_headers, custom_headers = {})
+      all_headers = base_headers.merge(custom_headers)
+      all_headers.merge!({'X-Request-Id' => Thread.current[:request_id]}) if config.include_request_id_header
+      all_headers
+    end
+
+    def get_headers
+      {
+        'Accept' => 'application/json',
+      }
+    end
+
+    def update_headers
+      {
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+    end
+
+
+
+    # def params_encoder
+    #   if HttpApiClient::rails_loaded?
+    #     RailsParamsEncoder
+    #   else
+
+    #   end
+    # end
+
+  end
+end

data/lib/http_api_client/config.rb

@@ -0,0 +1,58 @@
+# coding: utf-8
+
+require 'yaml'
+require 'ostruct'
+require 'http_api_client'
+
+module HttpApiClient
+  class Config
+
+    DEFAULT_CONFIG_FILE_LOCATION = 'config/http_api_clients.yml'
+
+    def initialize(config_file = DEFAULT_CONFIG_FILE_LOCATION)
+      if File.exists?(config_file)
+        @config = symbolize_keys(config_for(config_file, HttpApiClient.env))
+      else
+        raise "Could not load config file: #{config_file}"
+      end
+    end
+
+    private
+
+    attr_reader :config
+
+    def method_missing(method, *args, &block)
+      if config[method]
+        OpenStruct.new(config[method])
+      else
+        super
+      end
+    end
+
+    def config_for(config_file, environment)
+      all_config = YAML.load_file(config_file)
+      env_config = all_config[environment]
+      if env_config
+        env_config
+      else
+        raise "You must supply a http config for the '#{environment}' environment in '#{config_file}'."
+      end
+    end
+
+    def symbolize_keys(hash)
+      hash.inject({}) do |result, (key, value)|
+        new_key = case key
+              when String then key.to_sym
+              else key
+              end
+        new_value = case value
+                    when Hash then symbolize_keys(value)
+                    else value
+                    end
+        result[new_key] = new_value
+        result
+      end
+    end
+
+  end
+end

data/lib/http_api_client/connection_factory.rb

@@ -0,0 +1,58 @@
+require 'http_api_client/rails_params_encoder'
+
+module HttpApiClient
+  class ConnectionFactory
+
+    OSX_CERT_PATH = '/usr/local/opt/curl-ca-bundle/share/ca-bundle.crt'
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def create
+
+      Faraday.new(connection_options) do |connection|
+        connection.port = config.port if config.port
+        connection.request   :url_encoded    # form-encode POST params
+        connection.adapter   :net_http_persistent
+        # connection.use     :http_cache
+        # connection.response  :logger
+
+        if config.http_basic_username
+          connection.basic_auth(config.http_basic_username, config.http_basic_password)
+        end
+      end
+
+    end
+
+    private
+
+    def connection_options
+      options = { url: "#{config.protocol}://#{config.server}" }
+      options.merge!(ssl_config) if config.protocol == 'https'
+      options.merge!({ request: { params_encoder: HttpApiClient.params_encoder } }) if {}.respond_to?(:to_query)
+      options
+    end
+
+    def ssl_config
+      return { ssl: { ca_file: config.ca_file } }  if config.ca_file
+      return { ssl: { ca_file: osx_ssl_ca_file } } if osx?
+      return { ssl: { ca_path: '/etc/ssl/certs' } }
+    end
+
+    def osx?
+      `uname`.chomp == 'Darwin'
+    end
+
+    def osx_ssl_ca_file
+      if File.exists?(OSX_CERT_PATH)
+         OSX_CERT_PATH
+      else
+        raise "Unable to load certificate authority file at #{OSX_CERT_PATH}. Try `brew install curl-ca-bundle`"
+      end
+    end
+
+  end
+end

data/lib/http_api_client/errors.rb

@@ -0,0 +1,90 @@
+require 'http_api_client'
+
+module HttpApiClient
+
+  module Errors
+
+    class BaseError < StandardError
+
+      attr_reader :response_body, :nested_error
+
+      def initialize(message, response_body, nested_error = nil)
+        super(message)
+        @message = message
+        @response_body = response_body
+        @nested_error = nested_error
+      end
+
+      def message
+        messages = [@message]
+        messages << nested_error.message if nested_error
+        messages << response_body
+        messages.join("\n\n")
+      end
+
+    end
+
+    #400 Range
+    class BadRequest < BaseError ; end
+    class Unauthorized < BaseError ; end
+    class Forbidden < BaseError ; end
+    class NotFound < BaseError ; end
+    class MethodNotAllowed < BaseError ; end
+    class NotAcceptable < BaseError ; end
+    class RequestTimeout < BaseError ; end
+    class UnknownStatus < BaseError ; end
+    class UnprocessableEntity < BaseError ; end
+    class TooManyRequests < BaseError ; end
+
+    #500 Range
+    class InternalServerError < BaseError ; end
+    class NotImplemented < BaseError ; end
+    class BadGateway < BaseError ; end
+    class ServiceUnavailable < BaseError ; end
+    class GatewayTimeout < BaseError ; end
+
+    module Factory
+
+      def error_for_status(status)
+        case status
+        when 400
+          BadRequest
+        when 401
+          Unauthorized
+        when 403
+          Forbidden
+        when 404
+          NotFound
+        when 405
+          MethodNotAllowed
+        when 406
+          NotAcceptable
+        when 408
+          RequestTimeout
+
+        when 422
+          UnprocessableEntity
+
+        when 429
+          TooManyRequests
+
+        when 500
+          InternalServerError
+        when 501
+          NotImplemented
+        when 502
+          BadGateway
+        when 503
+          ServiceUnavailable
+        when 504
+           GatewayTimeout
+
+        else
+          UnknownStatus
+        end
+      end
+    end
+
+  end
+
+end

data/lib/http_api_client/rails_params_encoder.rb

@@ -0,0 +1,9 @@
+module HttpApiClient
+  module RailsParamsEncoder
+
+    def self.encode(params)
+      params.to_query
+    end
+
+  end
+end

data/lib/http_api_client/timed_result.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+class TimedResult
+
+  def self.time(event, log_data = {})
+    start_time = Time.now
+    yield
+  ensure
+
+    time = millis_since(start_time)
+
+    log_entries = ["event=#{event}"]
+    log_entries << "request_id=#{Thread.current[:request_id]}" if Thread.current[:request_id]
+    log_entries << "timing=#{time}"
+    log_entries.concat(log_data.to_param.split('&'))
+
+    HttpApiClient.logger.info(log_entries.join(", "))
+
+  end
+
+  def self.millis_since(start_time)
+    (Time.now - start_time) * 1000
+  end
+
+end

data/lib/http_api_client/version.rb

@@ -0,0 +1,3 @@
+module HttpApiClient
+  VERSION = "0.1.0"
+end