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_token=>'SOMECONSUMERTOKENFROMTWITTER',
  :token=>'ACCESSTOKENACQUIREDONUSERSBEHALF', :token_secret=>'SUPERSECRETACCESSTOKENSECRET'
})

Defined Under Namespace

Classes: Request

Constant Summary collapse

VALID_METHODS = 
[:get,:post,:put,:delete]
VALID_FORMATS = 
[:json,:xml,:atom,:rss]
TWITTER_API_HOSTS = 
{:rest=>'twitter.com',:search=>'search.twitter.com'}
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 or :search. :rest is the default

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

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

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



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/grackle/client.rb', line 104

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.headers = {"User-Agent"=>"Grackle/#{Grackle::VERSION}"}.merge!(options[:headers]||{})
  self.ssl = options[:ssl] == true
  self.api = options[:api] || :rest
  self.api_hosts = TWITTER_API_HOSTS.clone
  self.timeout = options[:timeout] || 60
  self.auth = {}
  if options.has_key?(:username) || options.has_key?(:password)
    #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) ⇒ Object 



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/grackle/client.rb', line 128

def method_missing(name,*args)
  #If method is a format name, execute using that format
  if format_invocation?(name)
    return call_with_format(name,*args)
  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
    self.request.method = ($2 == '!' ? :post : :get)          
    if format_invocation?(name)
      return call_with_format(name,*args)
    else
      self.request << "/#{$1}"
      return call_with_format(self.default_format,*args)
    end
  end
  #Else add to the request path
  self.request << "/#{name}"
  self
end

Instance Attribute Details

#api ⇒ Object

Returns the value of attribute api.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def api
  @api
end

#api_hosts ⇒ Object

Returns the value of attribute api_hosts.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def api_hosts
  @api_hosts
end

#auth ⇒ Object

Returns the value of attribute auth.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def auth
  @auth
end

#default_format ⇒ Object

Returns the value of attribute default_format.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def default_format
  @default_format
end

#handlers ⇒ Object

Returns the value of attribute handlers.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def handlers
  @handlers
end

#headers ⇒ Object

Returns the value of attribute headers.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def headers
  @headers
end

#request=(value) ⇒ Object

Sets the attribute request

Parameters:

  • value —

    the value to set the attribute request to.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def request=(value)
  @request = value
end

#ssl ⇒ Object

Returns the value of attribute ssl.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def ssl
  @ssl
end

#timeout ⇒ Object

Returns the value of attribute timeout.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def timeout
  @timeout
end

#transport ⇒ Object

Returns the value of attribute transport.



91
92
93
 
# File 'lib/grackle/client.rb', line 91

def transport
  @transport
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?



152
153
154
155
 
# File 'lib/grackle/client.rb', line 152

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

#clear ⇒ Object

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



158
159
160
 
# File 'lib/grackle/client.rb', line 158

def clear
  self.request = nil
end

#password ⇒ Object

Deprecated in favor of using the auth attribute.



178
179
180
181
182
 
# File 'lib/grackle/client.rb', line 178

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

#password=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



185
186
187
188
189
190
 
# File 'lib/grackle/client.rb', line 185

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.



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

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

#username=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



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

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