Module: HTTParty::ClassMethods

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

Overview

Common Request Options

Request methods (get, post, patch, 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.

:http_proxyuser:

User for proxy server authentication.

:http_proxypass:

Password for proxy server authentication.

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

:+local_host:

Local address to bind to before connecting.

:+local_port:

Local port to bind to before connecting.

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.

  • :connection_adapter: see HTTParty::ClassMethods.connection_adapter.

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

  • :query_string_normalizer: see HTTParty::ClassMethods.query_string_normalizer

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

  • :ssl_ca_path: see HTTParty::ClassMethods.ssl_ca_path.

Instance Method Summary (collapse)

Methods included from AllowedFormatsDeprecation

const_missing

Instance Method Details

- (Object) base_uri(uri = nil)

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


107
108
109
110
# File 'lib/httparty.rb', line 107

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

- (Object) basic_auth(u, p)

Allows setting basic authentication username and password.

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


118
119
120
# File 'lib/httparty.rb', line 118

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

- (Object) ciphers(cipher_names)

Allows setting of SSL ciphers to use. This only works in Ruby 1.9+. You can get a list of valid specific ciphers from OpenSSL::Cipher.ciphers. You also can specify a cipher suite here, listed here at openssl.org: www.openssl.org/docs/apps/ciphers.html#CIPHER_SUITE_NAMES

class Foo
  include HTTParty
  ciphers "RC4-SHA"
end


371
372
373
# File 'lib/httparty.rb', line 371

def ciphers(cipher_names)
  default_options[:ciphers] = cipher_names
end

- (Object) connection_adapter(custom_adapter = nil, options = nil)

Allows setting a custom connection_adapter for the http connections

Examples:

class Foo
  include HTTParty
  connection_adapter Proc.new {|uri, options| ... }
end

provide optional configuration for your connection_adapter

class Foo
  include HTTParty
  connection_adapter Proc.new {|uri, options| ... }, {:foo => :bar}
end

See Also:



435
436
437
438
439
440
441
442
# File 'lib/httparty.rb', line 435

def connection_adapter(custom_adapter = nil, options = nil)
  if custom_adapter.nil?
    default_options[:connection_adapter]
  else
    default_options[:connection_adapter] = custom_adapter
    default_options[:connection_adapter_options] = options
  end
end

- (Object) cookies(h = {})

Raises:

  • (ArgumentError)


224
225
226
227
# File 'lib/httparty.rb', line 224

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

- (Object) copy(path, options = {}, &block)

Perform a COPY request to a path



497
498
499
# File 'lib/httparty.rb', line 497

def copy(path, options={}, &block)
  perform_request Net::HTTP::Copy, path, options, &block
end

- (Object) debug_output(stream = $stderr)

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


208
209
210
# File 'lib/httparty.rb', line 208

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

- (Object) default_options

:nodoc:



511
512
513
# File 'lib/httparty.rb', line 511

def default_options #:nodoc:
  @default_options
end

- (Object) default_params(h = {})

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)


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

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

- (Object) default_timeout(t)

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

class Foo
  include HTTParty
  default_timeout 10
end

Raises:

  • (ArgumentError)


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

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

- (Object) delete(path, options = {}, &block)

Perform a DELETE request to a path



487
488
489
# File 'lib/httparty.rb', line 487

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

- (Object) digest_auth(u, p)

Allows setting digest authentication username and password.

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


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

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

- (Object) disable_rails_query_string_format

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


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

def disable_rails_query_string_format
  query_string_normalizer Request::NON_RAILS_QUERY_STRING_NORMALIZER
end

- (Object) follow_redirects(value = true)

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


238
239
240
# File 'lib/httparty.rb', line 238

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

- (Object) format(f = nil)

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


249
250
251
252
253
254
255
256
257
# File 'lib/httparty.rb', line 249

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

- (Object) get(path, options = {}, &block)

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})


456
457
458
# File 'lib/httparty.rb', line 456

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

- (Object) head(path, options = {}, &block)

Perform a HEAD request to a path



502
503
504
# File 'lib/httparty.rb', line 502

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

- (Object) headers(h = {})

Allows setting HTTP headers to be used for each request.

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

Raises:

  • (ArgumentError)


218
219
220
221
222
# File 'lib/httparty.rb', line 218

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

- (Object) http_proxy(addr = nil, port = nil, user = nil, pass = nil)

Allows setting http proxy information to be used

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


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

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

- (Object) logger(logger, level = :info, format = :apache)

Turns on logging

class Foo
  include HTTParty
  logger Logger.new('http_logger'), :info, :apache
end


81
82
83
84
85
# File 'lib/httparty.rb', line 81

def logger(logger, level=:info, format=:apache)
  default_options[:logger]     = logger
  default_options[:log_level]  = level
  default_options[:log_format] = format
end

- (Object) maintain_method_across_redirects(value = true)

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


293
294
295
# File 'lib/httparty.rb', line 293

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

- (Object) move(path, options = {}, &block)

Perform a MOVE request to a path



492
493
494
# File 'lib/httparty.rb', line 492

def move(path, options={}, &block)
  perform_request Net::HTTP::Move, path, options, &block
end

- (Object) no_follow(value = false)

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:



278
279
280
# File 'lib/httparty.rb', line 278

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

- (Object) open_timeout(t)

Allows setting a default open_timeout for all HTTP calls in seconds

class Foo
  include HTTParty
  open_timeout 10
end

Raises:

  • (ArgumentError)


185
186
187
188
# File 'lib/httparty.rb', line 185

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

- (Object) options(path, options = {}, &block)

Perform an OPTIONS request to a path



507
508
509
# File 'lib/httparty.rb', line 507

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

- (Object) parser(custom_parser = nil)

Allows setting a custom parser for the response.

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


411
412
413
414
415
416
417
418
# File 'lib/httparty.rb', line 411

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

- (Object) patch(path, options = {}, &block)

Perform a PATCH request to a path



477
478
479
# File 'lib/httparty.rb', line 477

def patch(path, options={}, &block)
  perform_request Net::HTTP::Patch, path, options, &block
end

- (Object) pem(pem_contents, password = nil)

Allows setting a PEM file to be used

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


303
304
305
306
# File 'lib/httparty.rb', line 303

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

- (Object) pkcs12(p12_contents, password)

Allows setting a PKCS12 file to be used

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


314
315
316
317
# File 'lib/httparty.rb', line 314

def pkcs12(p12_contents, password)
  default_options[:p12] = p12_contents
  default_options[:p12_password] = password
end

- (Object) post(path, options = {}, &block)

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'})


472
473
474
# File 'lib/httparty.rb', line 472

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

- (Object) put(path, options = {}, &block)

Perform a PUT request to a path



482
483
484
# File 'lib/httparty.rb', line 482

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

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

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 '&'



347
348
349
# File 'lib/httparty.rb', line 347

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

- (Object) read_timeout(t)

Allows setting a default read_timeout for all HTTP calls in seconds

class Foo
  include HTTParty
  read_timeout 10
end

Raises:

  • (ArgumentError)


196
197
198
199
# File 'lib/httparty.rb', line 196

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

- (Object) ssl_ca_file(path)

Allows setting an OpenSSL certificate authority file. The file should contain one or more certificates in PEM format.

Setting this option enables certificate verification. All certificates along a chain must be available in ssl_ca_file or ssl_ca_path for verification to succeed.

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


387
388
389
# File 'lib/httparty.rb', line 387

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

- (Object) ssl_ca_path(path)

Allows setting an OpenSSL certificate authority path (directory).

Setting this option enables certificate verification. All certificates along a chain must be available in ssl_ca_file or ssl_ca_path for verification to succeed.

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


401
402
403
# File 'lib/httparty.rb', line 401

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

- (Object) ssl_version(version)

Allows setting of SSL version to use. This only works in Ruby 1.9+. You can get a list of valid versions from OpenSSL::SSL::SSLContext::METHODS.

class Foo
  include HTTParty
  ssl_version :SSLv3
end


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

def ssl_version(version)
  default_options[:ssl_version] = version
end