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_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



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 105

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.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
149
150
151
152
153
154
155
156
 
# File 'lib/grackle/client.rb', line 128

def method_missing(name,*args)
  
  # if we only have a single String arg,
  # assume it's a query string (as in next_page on Search)
  # and parse it out
  if args[0].is_a?(String) && args.size == 1
    *args = parse_query(args[0][1..-1])
  end
  
  #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.



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

def api
  @api
end

#api_hosts ⇒ Object

Returns the value of attribute api_hosts.



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

def api_hosts
  @api_hosts
end

#auth ⇒ Object

Returns the value of attribute auth.



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

def auth
  @auth
end

#default_format ⇒ Object

Returns the value of attribute default_format.



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

def default_format
  @default_format
end

#handlers ⇒ Object

Returns the value of attribute handlers.



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

def handlers
  @handlers
end

#headers ⇒ Object

Returns the value of attribute headers.



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

def headers
  @headers
end

#request=(value) ⇒ Object

Sets the attribute request

Parameters:

  • value —

    the value to set the attribute request to.



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

def request=(value)
  @request = value
end

#ssl ⇒ Object

Returns the value of attribute ssl.



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

def ssl
  @ssl
end

#transport ⇒ Object

Returns the value of attribute transport.



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

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?



160
161
162
163
 
# File 'lib/grackle/client.rb', line 160

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

#clear ⇒ Object

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



166
167
168
 
# File 'lib/grackle/client.rb', line 166

def clear
  self.request = nil
end

#password ⇒ Object

Deprecated in favor of using the auth attribute.



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

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

#password=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



193
194
195
196
197
198
 
# File 'lib/grackle/client.rb', line 193

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.



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

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

#username=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



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

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