module Checkr

Constants

VERSION

Attributes

api_base[RW]
api_key[RW]
api_test[RW]

Public Class Methods

api_url(path='') click to toggle source
# File lib/checkr.rb, line 64
def self.api_url(path='')
  "#{@api_base}#{path}"
end
basic_auth_headers(api_key=@api_key) click to toggle source
# File lib/checkr.rb, line 133
def self.basic_auth_headers(api_key=@api_key)
  api_key ||= @api_key
  unless api_key
    raise ArgumentError.new('No API key provided. Set your API key using "Checkr.api_key = <API-KEY>".')
  end

  base_64_key = Base64.encode64("#{api_key}:")
  {
    "Authorization" => "Basic #{base_64_key}",
  }
end
connection_message() click to toggle source
# File lib/checkr.rb, line 228
def self.connection_message
  "Please check your internet connection and try again. " \
  "If this problem persists, you should check Checkr's service status at " \
  "https://twitter.com/checkrstatus, or let us know at hello@checkr.com."
end
default_headers() click to toggle source
# File lib/checkr.rb, line 118
def self.default_headers
  headers = {
    :user_agent => "Checkr/::API_VERSION:: RubyBindings/#{Checkr::VERSION}",
    :content_type => 'application/x-www-form-urlencoded'
  }

  begin
    headers.update(:x_checkr_client_user_agent => JSON.generate(user_agent))
  rescue => e
    headers.update(:x_checkr_client_raw_user_agent => user_agent.inspect,
                   :error => "#{e} (#{e.class})")
  end
  headers
end
execute_request(opts) click to toggle source

Mostly here for stubbing out during tests.

# File lib/checkr.rb, line 103
def self.execute_request(opts)
  RestClient::Request.execute(opts)
end
get_uname() click to toggle source
# File lib/checkr.rb, line 159
def self.get_uname
  `uname -a 2>/dev/null`.strip if RUBY_PLATFORM =~ /linux|darwin/i
rescue Errno::ENOMEM => ex # couldn't create subprocess
  "uname lookup failed"
end
handle_api_error(rcode, rbody) click to toggle source
# File lib/checkr.rb, line 234
def self.handle_api_error(rcode, rbody)
  begin
    error_obj = JSON.parse(rbody)
  rescue JSON::ParserError
    raise APIError.generic(rcode, rbody)
  end
  error_obj = Util.symbolize_keys(error_obj)
  raise APIError.generic(rcode, rbody) unless error = error_obj[:error]

  case rcode
  when 400, 404
    raise InvalidRequestError.new(error, "", rcode, rbody, error_obj)
  when 401
    raise AuthenticationError.new(error, rcode, rbody, error_obj)
  else
    raise APIError.new(error, rcode, rbody, error_obj)
  end
end
handle_connection_error(error, url) click to toggle source
# File lib/checkr.rb, line 199
def self.handle_connection_error(error, url)
  message = "An error occurred while connecting to Checkr at #{url}."

  case error
  when RestClient::RequestTimeout
    message +=  connection_message

  when RestClient::ServerBrokeConnection
    message = "The connection to the server at (#{url}) broke before the " \
      "request completed. #{connection_message}"

  when RestClient::SSLCertificateNotVerified
    message = "Could not verify Checkr's SSL certificate. " \
      "Please make sure that your network is not intercepting certificates. " \
      "If this problem persists, let us know at hello@checkr.com."

  when SocketError
    message = "Unexpected error when trying to connect to Checkr. " \
      "You may be seeing this message because your DNS is not working. " \
      "To check, try running 'host api.checkr.com' from the command line."

  else
    message = "Unexpected error communicating with Checkr. " \
      "If this problem persists, let us know at hello@checkr.com. #{connection_message}"
  end

  raise APIConnectionError.new(message + "\n\n(Network error: #{error.message}")
end
handle_request_error(error, url) click to toggle source
# File lib/checkr.rb, line 182
def self.handle_request_error(error, url)
  # First we see if this is an error with a response, and if it is
  # we check to see if there is an http code and body to work with.
  if error.is_a?(RestClient::ExceptionWithResponse)
    if error.http_code && error.http_body
      handle_api_error(error.http_code, error.http_body)
    end
  end

  # If we got here then the error hasn't been handled yet.
  # Handle it as a connection error.
  handle_connection_error(error, url)

  # Finally if we get here we don't know what type of error it is, so just raise it.
  raise error
end
parse(response) click to toggle source
# File lib/checkr.rb, line 107
def self.parse(response)
  begin
    json = JSON.parse(response.body)
  rescue JSON::ParserError
    raise APIError.generic(response.code, response.body)
  end

  json = Util.symbolize_keys(json)
  json
end
request(method, path, params={}, headers={}) click to toggle source
# File lib/checkr.rb, line 68
def self.request(method, path, params={}, headers={})
  api_key = params[:api_key] || self.api_key
  params.delete(:api_key)

  verify_api_key(api_key)

  url = api_url(path)

  request_opts = { :verify_ssl => false }

  if [:get, :head, :delete].include?(method.to_s.downcase.to_sym)
    unless params.empty?
      url += URI.parse(url).query ? '&' : '?' + Util.query_string(params)
    end
    params = nil
  end

  headers = default_headers.update(basic_auth_headers(api_key)).update(headers)
  request_opts.update(:headers => headers,
                      :method => method,
                      :open_timeout => 30,
                      :payload => params,
                      :url => url,
                      :timeout => 60)

  begin
    response = execute_request(request_opts)
  rescue Exception => e
    handle_request_error(e, url)
  end

  parse(response)
end
user_agent() click to toggle source
# File lib/checkr.rb, line 145
def self.user_agent
  @uname ||= get_uname
  lang_version = "#{RUBY_VERSION} p#{RUBY_PATCHLEVEL} (#{RUBY_RELEASE_DATE})"

  {
    :bindings_version => Checkr::VERSION,
    :lang => 'ruby',
    :lang_version => lang_version,
    :platform => RUBY_PLATFORM,
    :publisher => 'checkr',
    :uname => @uname
  }
end
verify_api_key(api_key) click to toggle source
# File lib/checkr.rb, line 165
def self.verify_api_key(api_key)
  unless api_key
    raise AuthenticationError.new('No API key provided. ' +
      'Set your API key using "Checkr.api_key = <API-KEY>". ' +
      'You can generate API keys from the Checkr web interface. ' +
      'See https://docs.checkr.com/#authentication for details, ' +
      'or email hello@checkr.com if you have any questions.')
  end

  if api_key =~ /\s/
    raise AuthenticationError.new('Your API key is invalid, as it contains ' +
      'whitespace. (HINT: You can double-check your API key from the ' +
      'Checkr web interface. See https://docs.checkr.com/#authentication for details, or ' +
      'email hello@checkr.com if you have any questions.)')
  end
end