Module: HTTParty::ClassMethods

Extended by:
AllowedFormatsDeprecation
Defined in:
lib/httparty.rb

Overview

Common Request Options

Request methods (get, post, put, delete, head, options) all take a common set of options. These are:

:body:

Body of the request. If passed a Hash, will try to normalize it first, by default passing it to ActiveSupport::to_params. Any other kind of object will get used as-is.

:http_proxyaddr:

Address of proxy server to use.

:http_proxyport:

Port of proxy server to use.

:limit:

Maximum number of redirects to follow. Takes precedences over :no_follow.

:query:

Query string, or a Hash representing it. Normalized according to the same rules as :body. If you specify this on a POST, you must use a Hash. See also HTTParty::ClassMethods.default_params.

:timeout:

Timeout for opening connection and reading data.

There are also another set of options with names corresponding to various class methods. The methods in question are those that let you set a class-wide default, and the options override the defaults on a request-by-request basis. Those options are:

  • :base_uri: see HTTParty::ClassMethods.base_uri.

  • :basic_auth: see HTTParty::ClassMethods.basic_auth. Only one of :basic_auth and :digest_auth can be used at a time; if you try using both, you’ll get an ArgumentError.

  • :debug_output: see HTTParty::ClassMethods.debug_output.

  • :digest_auth: see HTTParty::ClassMethods.digest_auth. Only one of :basic_auth and :digest_auth can be used at a time; if you try using both, you’ll get an ArgumentError.

  • :format: see HTTParty::ClassMethods.format.

  • :headers: see HTTParty::ClassMethods.headers. Must be a Hash.

  • :maintain_method_across_redirects: see HTTParty::ClassMethods.maintain_method_across_redirects.

  • :no_follow: see HTTParty::ClassMethods.no_follow.

  • :parser: see HTTParty::ClassMethods.parser.

  • :pem: see HTTParty::ClassMethods.pem.

  • :query_string_normalizer: see HTTParty::ClassMethods.query_string_normalizer

  • :ssl_ca_file: see HTTParty::ClassMethods.ssl_ca_file.

Instance Method Summary collapse

Methods included from AllowedFormatsDeprecation

const_missing

Instance Method Details

#base_uri(uri = nil) ⇒ Object

Allows setting a base uri to be used for each request. Will normalize uri to include http, etc.

class Foo
  include HTTParty
  base_uri 'twitter.com'
end



84
85
86
87
 
# File 'lib/httparty.rb', line 84

def base_uri(uri=nil)
  return default_options[:base_uri] unless uri
  default_options[:base_uri] = HTTParty.normalize_base_uri(uri)
end

#basic_auth(u, p) ⇒ Object

Allows setting basic authentication username and password.

class Foo
  include HTTParty
  basic_auth 'username', 'password'
end



95
96
97
 
# File 'lib/httparty.rb', line 95

def basic_auth(u, p)
  default_options[:basic_auth] = {:username => u, :password => p}
end

#cookies(h = {}) ⇒ Object

Raises:

  • (ArgumentError) 


179
180
181
182
 
# File 'lib/httparty.rb', line 179

def cookies(h={})
  raise ArgumentError, 'Cookies must be a hash' unless h.is_a?(Hash)
  default_cookies.add_cookies(h)
end

#debug_output(stream = $stderr) ⇒ Object

Set an output stream for debugging, defaults to $stderr. The output stream is passed on to Net::HTTP#set_debug_output.

class Foo
  include HTTParty
  debug_output $stderr
end



163
164
165
 
# File 'lib/httparty.rb', line 163

def debug_output(stream = $stderr)
  default_options[:debug_output] = stream
end

#default_options ⇒ Object

:nodoc:



382
383
384
 
# File 'lib/httparty.rb', line 382

def default_options #:nodoc:
  @default_options
end

#default_params(h = {}) ⇒ Object

Allows setting default parameters to be appended to each request. Great for api keys and such.

class Foo
  include HTTParty
  default_params :api_key => 'secret', :another => 'foo'
end

Raises:

  • (ArgumentError) 


138
139
140
141
142
 
# File 'lib/httparty.rb', line 138

def default_params(h={})
  raise ArgumentError, 'Default params must be a hash' unless h.is_a?(Hash)
  default_options[:default_params] ||= {}
  default_options[:default_params].merge!(h)
end

#default_timeout(t) ⇒ Object

Allows setting a default timeout for all HTTP calls Timeout is specified in seconds.

class Foo
  include HTTParty
  default_timeout 10
end

Raises:

  • (ArgumentError) 


151
152
153
154
 
# File 'lib/httparty.rb', line 151

def default_timeout(t)
  raise ArgumentError, 'Timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float))
  default_options[:timeout] = t
end

#delete(path, options = {}) ⇒ Object

Perform a DELETE request to a path



368
369
370
 
# File 'lib/httparty.rb', line 368

def delete(path, options={})
  perform_request Net::HTTP::Delete, path, options
end

#digest_auth(u, p) ⇒ Object

Allows setting digest authentication username and password.

class Foo
  include HTTParty
  digest_auth 'username', 'password'
end



105
106
107
 
# File 'lib/httparty.rb', line 105

def digest_auth(u, p)
  default_options[:digest_auth] = {:username => u, :password => p}
end

#disable_rails_query_string_format ⇒ Object

Do not send rails style query strings. Specically, don’t use bracket notation when sending an array

For a query:

get '/', :query => {:selected_ids => [1,2,3]}

The default query string looks like this:

/?selected_ids[]=1&selected_ids[]=2&selected_ids[]=3

Call disable_rails_query_string_format to transform the query string into:

/?selected_ids=1&selected_ids=2&selected_ids=3

Examples:

class Foo
  include HTTParty
  disable_rails_query_string_format
end


127
128
129
 
# File 'lib/httparty.rb', line 127

def disable_rails_query_string_format
  query_string_normalizer Request::NON_RAILS_QUERY_STRING_NORMALIZER
end

#follow_redirects(value = true) ⇒ Object

Proceed to the location header when an HTTP response dictates a redirect. Redirects are always followed by default.

Examples:

class Foo
  include HTTParty
  base_uri 'http://google.com'
  follow_redirects true
end


193
194
195
 
# File 'lib/httparty.rb', line 193

def follow_redirects(value = true)
  default_options[:follow_redirects] = value
end

#format(f = nil) ⇒ Object

Allows setting the format with which to parse. Must be one of the allowed formats ie: json, xml

class Foo
  include HTTParty
  format :json
end



204
205
206
207
208
209
210
211
212
 
# File 'lib/httparty.rb', line 204

def format(f = nil)
  if f.nil?
    default_options[:format]
  else
    parser(Parser) if parser.nil?
    default_options[:format] = f
    validate_format
  end
end

#get(path, options = {}) ⇒ Object

Allows making a get request to a url.

class Foo
  include HTTParty
end

# Simple get with full url
Foo.get('http://foo.com/resource.json')

# Simple get with full url and query parameters
# ie: http://foo.com/resource.json?limit=10
Foo.get('http://foo.com/resource.json', :query => {:limit => 10})



342
343
344
 
# File 'lib/httparty.rb', line 342

def get(path, options={})
  perform_request Net::HTTP::Get, path, options
end

#head(path, options = {}) ⇒ Object

Perform a HEAD request to a path



373
374
375
 
# File 'lib/httparty.rb', line 373

def head(path, options={})
  perform_request Net::HTTP::Head, path, options
end

#headers(h = {}) ⇒ Object

Allows setting HTTP headers to be used for each request.

class Foo
  include HTTParty
  headers 'Accept' => 'text/html'
end

Raises:

  • (ArgumentError) 


173
174
175
176
177
 
# File 'lib/httparty.rb', line 173

def headers(h={})
  raise ArgumentError, 'Headers must be a hash' unless h.is_a?(Hash)
  default_options[:headers] ||= {}
  default_options[:headers].merge!(h)
end

#http_proxy(addr = nil, port = nil) ⇒ Object

Allows setting http proxy information to be used

class Foo
  include HTTParty
  http_proxy 'http://foo.com', 80
end



72
73
74
75
 
# File 'lib/httparty.rb', line 72

def http_proxy(addr=nil, port = nil)
  default_options[:http_proxyaddr] = addr
  default_options[:http_proxyport] = port
end

#maintain_method_across_redirects(value = true) ⇒ Object

Declare that you wish to maintain the chosen HTTP method across redirects. The default behavior is to follow redirects via the GET method. If you wish to maintain the original method, you can set this option to true.

Examples:

class Foo
  include HTTParty
  base_uri 'http://google.com'
  maintain_method_across_redirects true
end


248
249
250
 
# File 'lib/httparty.rb', line 248

def maintain_method_across_redirects(value = true)
  default_options[:maintain_method_across_redirects] = value
end

#no_follow(value = false) ⇒ Object

Declare whether or not to follow redirects. When true, an RedirectionTooDeep error will raise upon encountering a redirect. You can then gain access to the response object via HTTParty::RedirectionTooDeep#response.

Examples:

class Foo
  include HTTParty
  base_uri 'http://google.com'
  no_follow true
end

begin
  Foo.get('/')
rescue HTTParty::RedirectionTooDeep => e
  puts e.response.body
end

See Also:



233
234
235
 
# File 'lib/httparty.rb', line 233

def no_follow(value = false)
  default_options[:no_follow] = value
end

#options(path, options = {}) ⇒ Object

Perform an OPTIONS request to a path



378
379
380
 
# File 'lib/httparty.rb', line 378

def options(path, options={})
  perform_request Net::HTTP::Options, path, options
end

#parser(custom_parser = nil) ⇒ Object

Allows setting a custom parser for the response.

class Foo
  include HTTParty
  parser Proc.new {|data| ...}
end



321
322
323
324
325
326
327
328
 
# File 'lib/httparty.rb', line 321

def parser(custom_parser = nil)
  if custom_parser.nil?
    default_options[:parser]
  else
    default_options[:parser] = custom_parser
    validate_format
  end
end

#pem(pem_contents, password = nil) ⇒ Object

Allows setting a PEM file to be used

class Foo
  include HTTParty
  pem File.read('/home/user/my.pem'), "optional password"
end



258
259
260
261
 
# File 'lib/httparty.rb', line 258

def pem(pem_contents, password=nil)
  default_options[:pem] = pem_contents
  default_options[:pem_password] = password
end

#post(path, options = {}) ⇒ Object

Allows making a post request to a url.

class Foo
  include HTTParty
end

# Simple post with full url and setting the body
Foo.post('http://foo.com/resources', :body => {:bar => 'baz'})

# Simple post with full url using :query option,
# which gets set as form data on the request.
Foo.post('http://foo.com/resources', :query => {:bar => 'baz'})



358
359
360
 
# File 'lib/httparty.rb', line 358

def post(path, options={})
  perform_request Net::HTTP::Post, path, options
end

#put(path, options = {}) ⇒ Object

Perform a PUT request to a path



363
364
365
 
# File 'lib/httparty.rb', line 363

def put(path, options={})
  perform_request Net::HTTP::Put, path, options
end

#query_string_normalizer(normalizer) {|Hash, String| ... } ⇒ Object

Override the way query strings are normalized. Helpful for overriding the default rails normalization of Array queries.

For a query:

get '/', :query => {:selected_ids => [1,2,3]}

The default query string normalizer returns:

/?selected_ids[]=1&selected_ids[]=2&selected_ids[]=3

Let’s change it to this:

/?selected_ids=1&selected_ids=2&selected_ids=3

Pass a Proc to the query normalizer which accepts the yielded query.

Examples:

Modifying Array query strings

class ServiceWrapper
  include HTTParty

  query_string_normalizer proc { |query|
    query.map do |key, value|
      value.map {|v| "#{key}=#{v}"}
    end.join('&')
  }
end

Parameters:

  • normalizer (Proc) —

    custom query string normalizer.

Yields:

  • (Hash, String) —

    query string

Yield Returns:

  • (Array) —

    an array that will later be joined with ‘&’



291
292
293
 
# File 'lib/httparty.rb', line 291

def query_string_normalizer(normalizer)
  default_options[:query_string_normalizer] = normalizer
end

#ssl_ca_file(path) ⇒ Object

Allows setting an OpenSSL certificate authority file

class Foo
  include HTTParty
  ssl_ca_file '/etc/ssl/certs/ca-certificates.crt'
end



301
302
303
 
# File 'lib/httparty.rb', line 301

def ssl_ca_file(path)
  default_options[:ssl_ca_file] = path
end

#ssl_ca_path(path) ⇒ Object

Allows setting an OpenSSL certificate authority path (directory)

class Foo
  include HTTParty
  ssl_ca_path '/etc/ssl/certs/'
end



311
312
313
 
# File 'lib/httparty.rb', line 311

def ssl_ca_path(path)
  default_options[:ssl_ca_path] = path
end