class OctocatHerder::Connection

This implements some additional functionality around HTTParty to help make working with the GitHub API a little nicer.

Attributes

oauth2_token[R]

The OAuth2 token to use when doing OAuth2 authentication.

@since 0.0.1

password[R]

Password to use when doing basic HTTP authentication.

@since 0.0.1

user_name[R]

User name to use when doing basic HTTP authentication.

@since 0.0.1

Public Class Methods

new(options={}) click to toggle source

If provided a hash of login information, the {OctocatHerder::Connection} will attempt to make authenticated requests.

@example Unauthenticated requests

connection = OctocatHerder::Connection.new

@example Providing an OAuth2 token

connection = OctocatHerder::Connection.new :oauth2_token => 'token'

@example Providing user name & password

connection = OctocatHerder::Connection.new :user_name => 'user', :password => 'pass'

If no hash is provided, then unauthenticated requests will be made.

@since 0.0.1 @param [Hash<Symbol => String>] options Login information @option options [String] :user_name @option options [String] :password @option options [String] :oauth2_token

# File lib/octocat_herder/connection.rb, line 47
def initialize(options={})
  raise ArgumentError.new(
    "OctocatHerder::Connection does not accept: #{options.class}"
  ) unless options.is_a? Hash

  options.keys.each do |k|
    raise ArgumentError.new("Unknown option: '#{k}'") unless [
      :user_name, :password, :oauth2_token
    ].include? k
  end

  if options.keys.include?(:user_name) or options.keys.include?(:password)
    raise ArgumentError.new("When providing :user_name or :password, both are required") unless
      options.keys.include?(:user_name) and options.keys.include?(:password)
  end

  if options.keys.include?(:oauth2_token) and options.keys.include?(:user_name)
    raise ArgumentError.new('Cannot provide both an OAuth2 token, and a user name and password')
  end

  @user_name    = options[:user_name]
  @password     = options[:password]
  @oauth2_token = options[:oauth2_token]

  if oauth2_token
    @httparty_options = { :headers => { 'Authorization' => "token #{oauth2_token}" } }
  elsif user_name
    @httparty_options = { :basic_auth => { :username => user_name, :password => password } }
  end
end

Public Instance Methods

authenticated_requests?() click to toggle source

Are we making authenticated requests?

@since 0.1.0 @return [true, false]

# File lib/octocat_herder/connection.rb, line 138
def authenticated_requests?
  if (user_name and password) or oauth2_token
    true
  else
    false
  end
end
get(end_point, options={}) click to toggle source

Execute a GET request against the GitHub v3 API.

@since 0.1.0

@param [String] end_point The part of the API URL after

+'api.github.com'+, including the leading +'/'+.

@param [Hash] options A Hash of options to be passed down to

HTTParty, with a couple of extra options.

@option options [true, false] :paginated Retrieve all pages from

a paginated end-point.

@option options [Hash<String, Symbol => String>] :params

Constructed into a query string using
{OctocatHerder::Connection#query_string_from_params}.
# File lib/octocat_herder/connection.rb, line 94
def get(end_point, options={})
  paginated = options.delete(:paginated)
  options[:params] ||= {}

  options[:params][:per_page] = 100 if paginated and options[:params][:per_page].nil?

  result = raw_get(end_point, options)
  raise "Unable to retrieve #{end_point}" unless result

  full_result = result.parsed_response

  if paginated
    if next_page = page_from_headers(result.headers, 'next')
      options[:params][:page] = next_page
      options[:paginated]     = true

      full_result += raw_get(end_point, options)
    end
  end

  full_result
end
page_from_headers(headers, type) click to toggle source

Retrieve the page number of a given ‘Link:’ header from a hash of HTTP Headers

type can be one of:

next

The immediate next page of results.

last

The last page of first.

first

The first page of results.

prev

The immediate previous page of results.

@since 0.1.0

@raise [ArgumentError] If type is not one of the allowed values.

@param [Hash] headers

@param [‘next’, ‘last’, ‘first’, ‘prev’] type

# File lib/octocat_herder/connection.rb, line 162
def page_from_headers(headers, type)
  raise ArgumentError.new(
    "Unknown type: #{type}"
  ) unless ['next', 'last', 'first', 'prev'].include? type

  link = LinkHeader.parse(headers['link']).find_link(['rel', type])
  return unless link

  CGI.parse(URI.parse(link.href).query)['page'].first
end
query_string_from_params(params) click to toggle source

Convenience method to generate URL query strings.

@since 0.1.0

@param [Hash] params A Hash of key/values to be turned into a

URL query string.  Does not support nested data.

@return [String] Empty string if params is an empty hash,

otherwise a string of the query parameters with a leading
+'?'+.
# File lib/octocat_herder/connection.rb, line 183
def query_string_from_params(params)
  return '' if params.keys.empty?

  '?' + params.map {|k,v| "#{URI.escape("#{k}")}=#{URI.escape("#{v}")}"}.join('&')
end
raw_get(end_point, options={}) click to toggle source

Small wrapper around HTTParty.get, which handles adding authentication information to the API request.

@since 0.1.0

# File lib/octocat_herder/connection.rb, line 121
def raw_get(end_point, options={})
  options = options.dup
  query_params = options.delete(:params) || {}
  query_string = query_string_from_params(query_params)

  request_options = options.merge(httparty_options)
  if httparty_options.has_key?(:headers) and options.has_key(:headers)
    request_options[:headers] = options[:headers].merge(httparty_options[:headers])
  end

  OctocatHerder::Connection.get(end_point + query_string, request_options)
end

Private Instance Methods

httparty_options() click to toggle source
# File lib/octocat_herder/connection.rb, line 191
def httparty_options
  @httparty_options || {}
end