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]
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.

{
  :search=>'search.twitter.com', :v1=>'api.twitter.com/1', :upload=>'upload.twitter.com/1'
}
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 or :v1. :v1 is the default and :rest is now deprecated

  • :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

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



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/grackle/client.rb', line 115

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] || :v1
  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.uri_extension = options[:uri_extension] == false ? false : true
  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, &block) ⇒ Object 



141
142
143
144
145
146
 
# File 'lib/grackle/client.rb', line 141

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.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def api
  @api
end

#api_hosts ⇒ Object

Returns the value of attribute api_hosts.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def api_hosts
  @api_hosts
end

#auth ⇒ Object

Returns the value of attribute auth.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def auth
  @auth
end

#auto_append_ids ⇒ Object

Returns the value of attribute auto_append_ids.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def auto_append_ids
  @auto_append_ids
end

#default_format ⇒ Object

Returns the value of attribute default_format.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def default_format
  @default_format
end

#handlers ⇒ Object

Returns the value of attribute handlers.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def handlers
  @handlers
end

#headers ⇒ Object

Returns the value of attribute headers.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def headers
  @headers
end

#request=(value) ⇒ Object

Sets the attribute request

Parameters:

  • value —

    the value to set the attribute request to.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def request=(value)
  @request = value
end

#ssl ⇒ Object

Returns the value of attribute ssl.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def ssl
  @ssl
end

#timeout ⇒ Object

Returns the value of attribute timeout.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def timeout
  @timeout
end

#transport ⇒ Object

Returns the value of attribute transport.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

def transport
  @transport
end

#uri_extension ⇒ Object

Returns the value of attribute uri_extension.



100
101
102
 
# File 'lib/grackle/client.rb', line 100

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



150
151
152
153
 
# File 'lib/grackle/client.rb', line 150

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

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



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/grackle/client.rb', line 190

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



156
157
158
 
# File 'lib/grackle/client.rb', line 156

def clear
  self.request = nil
end

#password ⇒ Object

Deprecated in favor of using the auth attribute.



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

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

#password=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



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

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.



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

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

#username=(value) ⇒ Object

Deprecated in favor of using the auth attribute.



168
169
170
171
172
173
 
# File 'lib/grackle/client.rb', line 168

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