Class: Grackle::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/grackle/client.rb

Overview

The Client is the public interface to Grackle. You build Twitter API calls using method chains. See the README for details and new for information on valid options.

Authentication

Twitter is migrating to OAuth as the preferred mechanism for authentication (over HTTP basic auth). Grackle supports both methods. Typically you will supply Grackle with authentication information at the time you create your Grackle::Client via the :auth parameter.

Basic Auth

client = Grackle.Client.new(:auth=>{:type=>:basic,:username=>'twitteruser',:password=>'secret'})

Please note that the original way of specifying basic authentication still works but is deprecated

client = Grackle.Client.new(:username=>'twitteruser',:password=>'secret') #deprecated

OAuth

OAuth is a relatively complex topic. For more information on OAuth applications see the official OAuth site at oauth.net and the OAuth specification at oauth.net/core/1.0. For authentication using OAuth, you will need do the following:

  • Acquire a key and token for your application (“Consumer” in OAuth terms) from Twitter. Learn more here: apiwiki.twitter.com/OAuth-FAQ

  • Acquire an access token and token secret for the user that will be using OAuth to authenticate into Twitter

The process of acquiring the access token and token secret are outside the scope of Grackle and will need to be coded on a per-application basis. Grackle comes into play once you’ve acquired all of the above pieces of information. To create a Grackle::Client that uses OAuth once you’ve got all the necessary tokens and keys:

client = Grackle::Client.new(:auth=>{
  :type=>:oauth,
  :consumer_key=>'SOMECONSUMERKEYFROMTWITTER, :consumer_secret=>'SOMECONSUMERTOKENFROMTWITTER',
  :token=>'ACCESSTOKENACQUIREDONUSERSBEHALF', :token_secret=>'SUPERSECRETACCESSTOKENSECRET'
})

Defined Under Namespace

Classes: Request

Constant Summary collapse

VALID_FORMATS = 
[:json,:xml,:atom,:rss]
VALID_HTTP_CODES = 
[200]
TWITTER_API_HOSTS =

Contains the mapping of API name symbols to actual host (and path) prefixes to use with requests. You can add your own to this hash and refer to it wherever Grackle::Client uses an API symbol. You may wish to do this when Twitter introduces API versions greater than 1.

{
  :v1=>'api.twitter.com/1', :v1_1=>'api.twitter.com/1.1',
  :search=>'search.twitter.com',
  :upload=>'upload.twitter.com/1'
}
DEFAULT_API_HOST = 
:v1_1
DEFAULT_RESPONSE_HEADERS =

Contains the response headers from twitter

[
  # These are API 1 rate limit header names
  'x-ratelimit-limit',
  'x-ratelimit-remaining',
  'x-ratelimit-reset',
  # These are API 1.1 rate limit header names
  'x-rate-limit-limit',
  'x-rate-limit-remaining',
  'x-rate-limit-reset'
]
TWITTER_OAUTH_SPEC =

Basic OAuth information needed to communicate with Twitter

{
  :request_token_path=>'/oauth/request_token',
  :access_token_path=>'/oauth/access_token',
  :authorize_path=>'/oauth/authorize'
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Arguments (all are optional):

  • :username - Twitter username to authenticate with (deprecated in favor of :auth arg)

  • :password - Twitter password to authenticate with (deprecated in favor of :auth arg)

  • :handlers - Hash of formats to Handler instances (e.g. Grackle::Client.:json=>CustomJSONHandler:json=>CustomJSONHandler.new)

  • :default_format - Symbol of format to use when no format is specified in an API call (e.g. :json, :xml)

  • :headers - Hash of string keys and values for headers to pass in the HTTP request to twitter

  • :ssl - true or false to turn SSL on or off. Default is off (i.e. http://)

  • :api - one of :rest, :search, :v1 or :v1_1. :v1_1 is the default. :rest and :search are now deprecated

  • :auth - Hash of authentication type and credentials. Must have :type key with value one of :basic or :oauth

    • :type=>:oauth - Include :consumer_key, :consumer_secret, :token and :token_secret keys

    • :type=>:basic - DEPRECATED. Include :username and :password keys

  • :auto_append_format - true or false to include format in URI (e.g. /test.json). Default is true

  • :response_headers - array of headers to return from the response

  • :valid_http_codes - array of HTTP codes to consider valid (non-error)



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/grackle/client.rb', line 134

def initialize(options={})
  self.transport = Transport.new
  self.handlers = {:json=>Handlers::JSONHandler.new,:xml=>Handlers::XMLHandler.new,:unknown=>Handlers::StringHandler.new}
  self.handlers.merge!(options[:handlers]||{})
  self.default_format = options[:default_format] || :json
  self.auto_append_format = options[:auto_append_format] == false ? false : true
  self.headers = {"User-Agent"=>"Grackle/#{Grackle::VERSION}"}.merge!(options[:headers]||{})
  self.ssl = options[:ssl] == true
  self.api = options[:api] || DEFAULT_API_HOST
  self.api_hosts = TWITTER_API_HOSTS.clone
  self.timeout = options[:timeout] || 60
  self.auto_append_ids = options[:auto_append_ids] == false ? false : true
  self.auth = {}
  self.response_headers = options[:response_headers] || DEFAULT_RESPONSE_HEADERS.clone
  self.valid_http_codes = options[:valid_http_codes] || VALID_HTTP_CODES.clone
  if options.has_key?(:username) || options.has_key?(:password)
    # DEPRECATED: Use basic auth if :username and :password args are passed in
    self.auth.merge!({:type=>:basic,:username=>options[:username],:password=>options[:password]})
  end
  #Handle auth mechanism that permits basic or oauth
  if options.has_key?(:auth)
    self.auth = options[:auth]
    if auth[:type] == :oauth
      self.auth = TWITTER_OAUTH_SPEC.merge(auth)
    end
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, &block) ⇒ Object 



162
163
164
165
166
167
 
# File 'lib/grackle/client.rb', line 162

def method_missing(name,*args,&block)
  if block_given?
    return request_with_http_method_block(name,&block)
  end
  append(name,*args)
end

Instance Attribute Details

#api ⇒ Object

Returns the value of attribute api.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def api
  @api
end

#api_hosts ⇒ Object

Returns the value of attribute api_hosts.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def api_hosts
  @api_hosts
end

#auth ⇒ Object

Returns the value of attribute auth.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def auth
  @auth
end

#auto_append_format ⇒ Object

Returns the value of attribute auto_append_format.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def auto_append_format
  @auto_append_format
end

#auto_append_ids ⇒ Object

Returns the value of attribute auto_append_ids.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def auto_append_ids
  @auto_append_ids
end

#default_format ⇒ Object

Returns the value of attribute default_format.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def default_format
  @default_format
end

#handlers ⇒ Object

Returns the value of attribute handlers.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def handlers
  @handlers
end

#headers ⇒ Object

Returns the value of attribute headers.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def headers
  @headers
end

#request=(value) ⇒ Object

Sets the attribute request

Parameters:

  • value —

    the value to set the attribute request to.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def request=(value)
  @request = value
end

#response ⇒ Object

Returns the value of attribute response.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def response
  @response
end

#response_headers ⇒ Object

Returns the value of attribute response_headers.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def response_headers
  @response_headers
end

#ssl ⇒ Object

Returns the value of attribute ssl.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def ssl
  @ssl
end

#timeout ⇒ Object

Returns the value of attribute timeout.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def timeout
  @timeout
end

#transport ⇒ Object

Returns the value of attribute transport.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def transport
  @transport
end

#valid_http_codes ⇒ Object

Returns the value of attribute valid_http_codes.



116
117
118
 
# File 'lib/grackle/client.rb', line 116

def valid_http_codes
  @valid_http_codes
end

Instance Method Details

#[](api_name) ⇒ Object

Used to toggle APIs for a particular request without setting the Client’s default API

client[:rest].users.show.hayesdavis?



171
172
173
174
 
# File 'lib/grackle/client.rb', line 171

def [](api_name)
  request.api = api_name
  self
end

#append(name, *args) ⇒ Object Also known as: _ 



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/grackle/client.rb', line 211

def append(name,*args)
  name = name.to_s.to_sym
  #The args will be a hash, store them if they're specified
  self.request.params = args.first
  #If method is a format name, execute using that format
  if format_invocation?(name)
    return call_with_format(name)
  end
  #If method ends in ! or ? use that to determine post or get
  if name.to_s =~ /^(.*)(!|\?)$/
    name = $1.to_sym
    #! is a post, ? is a get - only set this if the method hasn't been set
    self.request.method ||= ($2 == '!' ? :post : :get)          
    if format_invocation?(name)
      return call_with_format(name)
    else
      self.request << "/#{$1}"
      return call_with_format(self.default_format)
    end
  end
  #Else add to the request path
  self.request << "/#{name}"
  self
end

#clear ⇒ Object

Clears any pending request built up by chained methods but not executed



177
178
179
 
# File 'lib/grackle/client.rb', line 177

def clear
  self.request = nil
end

#password ⇒ Object

Deprecated in favor of using the auth attribute.



197
198
199
200
201
 
# File 'lib/grackle/client.rb', line 197

def password
  if auth[:type] == :basic
    auth[:password]
  end
end

#password=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



204
205
206
207
208
209
 
# File 'lib/grackle/client.rb', line 204

def password=(value)
  unless auth[:type] == :basic
    auth[:type] = :basic
  end
  auth[:password] = value
end

#username ⇒ Object

Deprecated in favor of using the auth attribute.



182
183
184
185
186
 
# File 'lib/grackle/client.rb', line 182

def username
  if auth[:type] == :basic
    auth[:username]
  end
end

#username=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



189
190
191
192
193
194
 
# File 'lib/grackle/client.rb', line 189

def username=(value)
  unless auth[:type] == :basic
    auth[:type] = :basic        
  end
  auth[:username] = value
end