Module: HTTParty::ClassMethods

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 an object that responds to #to_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 an object that responds to #to_hash representing it. Normalized according to the same rules as :+body+. If you specify this on a POST, you must use an object which responds to #to_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. [:+body_stream+:] Allow streaming to a REST server to specify a body_stream. [:+stream_body+:] When downloading with a block, avoids accumulating the response in memory. When uploading files, streams the request body to reduce memory usage (opt-in). [:+multipart+:] Force content-type to be multipart

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 an object which responds to #to_hash.
  • :+maintain_method_across_redirects+: see HTTParty::ClassMethods.maintain_method_across_redirects.
  • :+no_follow+: see HTTParty::ClassMethods.no_follow.
  • :+parser+: see HTTParty::ClassMethods.parser.
  • :+uri_adapter+: see HTTParty::ClassMethods.uri_adapter
  • :+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 Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#default_options ⇒ Object (readonly)

Returns the value of attribute default_options.



607
608
609
 
# File 'lib/httparty.rb', line 607

def default_options
  @default_options
end

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


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

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


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

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

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



600
601
602
603
604
605
 
# File 'lib/httparty.rb', line 600

def build_request(http_method, path, options = {})
  options = ModuleInheritableAttributes.hash_deep_dup(default_options).merge(options)
  HeadersProcessor.new(headers, options).call
  process_cookies(options)
  Request.new(http_method, path, options)
end

#ciphers(cipher_names) ⇒ Object

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: http://www.openssl.org/docs/apps/ciphers.html#CIPHER_SUITE_NAMES

class Foo
include HTTParty
ciphers "RC4-SHA"
end


435
436
437
 
# File 'lib/httparty.rb', line 435

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

#connection_adapter(custom_adapter = nil, options = nil) ⇒ Object

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:



510
511
512
513
514
515
516
517
 
# File 'lib/httparty.rb', line 510

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

#cookies(h = {}) ⇒ Object

Raises:

  • (ArgumentError) 


252
253
254
255
 
# File 'lib/httparty.rb', line 252

def cookies(h = {})
  raise ArgumentError, 'Cookies must be an object which responds to #to_hash' unless h.respond_to?(:to_hash)
  default_cookies.add_cookies(h)
end

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

Perform a COPY request to a path



572
573
574
 
# File 'lib/httparty.rb', line 572

def copy(path, options = {}, &block)
  perform_request Net::HTTP::Copy, path, options, &block
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


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

def debug_output(stream = $stderr)
  default_options[:debug_output] = stream
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) 


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

def default_params(h = {})
  raise ArgumentError, 'Default params must be an object which responds to #to_hash' unless h.respond_to?(:to_hash)
  default_options[:default_params] ||= {}
  default_options[:default_params].merge!(h)
end

#default_timeout(value) ⇒ Object

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

class Foo
include HTTParty
default_timeout 10
end


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

def default_timeout(value)
  validate_timeout_argument(__method__, value)
  default_options[:timeout] = value
end

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

Perform a DELETE request to a path



562
563
564
 
# File 'lib/httparty.rb', line 562

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

#digest_auth(u, p) ⇒ Object

Allows setting digest authentication username and password.

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


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

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. Specifically, 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


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

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


266
267
268
 
# File 'lib/httparty.rb', line 266

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


277
278
279
280
281
282
283
284
285
 
# File 'lib/httparty.rb', line 277

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

#foul(bool) ⇒ Object

Turns on or off the foul option.

class Foo
include HTTParty
foul true
end


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

def foul(bool)
  default_options[:foul] = bool
end

#get(path, options = {}, &block) ⇒ 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})


531
532
533
 
# File 'lib/httparty.rb', line 531

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

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

Perform a HEAD request to a path



577
578
579
580
 
# File 'lib/httparty.rb', line 577

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

#headers(h = nil) ⇒ Object

Allows setting HTTP headers to be used for each request.

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


242
243
244
245
246
247
248
249
250
 
# File 'lib/httparty.rb', line 242

def headers(h = nil)
  if h
    raise ArgumentError, 'Headers must be an object which responds to #to_hash' unless h.respond_to?(:to_hash)
    default_options[:headers] ||= {}
    default_options[:headers].merge!(h.to_hash)
  else
    default_options[:headers] || {}
  end
end

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

Allows setting http proxy information to be used

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


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

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

#lock(path, options = {}, &block) ⇒ Object 



592
593
594
 
# File 'lib/httparty.rb', line 592

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

#logger(logger, level = :info, format = :apache) ⇒ Object

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

#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, except if you are making a HEAD request, in which case the default is to follow all redirects with HEAD requests. 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


323
324
325
 
# File 'lib/httparty.rb', line 323

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

#mkcol(path, options = {}, &block) ⇒ Object

Perform a MKCOL request to a path



588
589
590
 
# File 'lib/httparty.rb', line 588

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

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

Perform a MOVE request to a path



567
568
569
 
# File 'lib/httparty.rb', line 567

def move(path, options = {}, &block)
  perform_request Net::HTTP::Move, path, options, &block
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:



306
307
308
 
# File 'lib/httparty.rb', line 306

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

#open_timeout(value) ⇒ Object

Allows setting a default open_timeout for all HTTP calls in seconds

class Foo
include HTTParty
open_timeout 10
end


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

def open_timeout(value)
  validate_timeout_argument(__method__, value)
  default_options[:open_timeout] = value
end

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

Perform an OPTIONS request to a path



583
584
585
 
# File 'lib/httparty.rb', line 583

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

#parser(custom_parser = nil) ⇒ Object

Allows setting a custom parser for the response.

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


475
476
477
478
479
480
481
482
 
# File 'lib/httparty.rb', line 475

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

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

Perform a PATCH request to a path



552
553
554
 
# File 'lib/httparty.rb', line 552

def patch(path, options = {}, &block)
  perform_request Net::HTTP::Patch, path, options, &block
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


351
352
353
354
 
# File 'lib/httparty.rb', line 351

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

#pkcs12(p12_contents, password) ⇒ Object

Allows setting a PKCS12 file to be used

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


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

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

#post(path, options = {}, &block) ⇒ 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 appends the parameters to the URI.
Foo.post('http://foo.com/resources', query: {bar: 'baz'})


547
548
549
 
# File 'lib/httparty.rb', line 547

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

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

Perform a PUT request to a path



557
558
559
 
# File 'lib/httparty.rb', line 557

def put(path, options = {}, &block)
  perform_request Net::HTTP::Put, path, options, &block
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 '&'



395
396
397
 
# File 'lib/httparty.rb', line 395

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

#raise_on(codes = []) ⇒ Object

Raises HTTParty::ResponseError if the response status matches a code, range, or regular expression string.

class Foo
include HTTParty
raise_on [404, 500..599, '3[0-9]*']
end


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

def raise_on(codes = [])
  default_options[:raise_on] = codes.is_a?(Range) ? [codes] : [*codes]
end

#read_timeout(value) ⇒ Object

Allows setting a default read_timeout for all HTTP calls in seconds

class Foo
include HTTParty
read_timeout 10
end


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

def read_timeout(value)
  validate_timeout_argument(__method__, value)
  default_options[:read_timeout] = value
end

#resend_on_redirect(value = true) ⇒ Object

Declare that you wish to resend the full HTTP request across redirects, even on redirects that should logically become GET requests. A 303 redirect in HTTP signifies that the redirected url should normally retrieved using a GET request, for instance, it is the output of a previous POST. maintain_method_across_redirects respects this behavior, but you can force HTTParty to resend_on_redirect even on 303 responses.

Examples:

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


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

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

#skip_decompression(value = true) ⇒ Object

Deactivate automatic decompression of the response body. This will require you to explicitly handle body decompression by inspecting the Content-Encoding response header.

Refer to docs/README.md "HTTP Compression" section for further details.

Examples:

class Foo
  include HTTParty
  skip_decompression
end


422
423
424
 
# File 'lib/httparty.rb', line 422

def skip_decompression(value = true)
  default_options[:skip_decompression] = !!value
end

#ssl_ca_file(path) ⇒ Object

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


451
452
453
 
# File 'lib/httparty.rb', line 451

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

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


465
466
467
 
# File 'lib/httparty.rb', line 465

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

#ssl_version(version) ⇒ Object

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


406
407
408
 
# File 'lib/httparty.rb', line 406

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

#unlock(path, options = {}, &block) ⇒ Object 



596
597
598
 
# File 'lib/httparty.rb', line 596

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

#uri_adapter(uri_adapter) ⇒ Object

Allows setting a custom URI adapter.

class Foo
include HTTParty
uri_adapter Addressable::URI
end

Raises:

  • (ArgumentError) 


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

def uri_adapter(uri_adapter)
  raise ArgumentError, 'The URI adapter should respond to #parse' unless uri_adapter.respond_to?(:parse)
  default_options[:uri_adapter] = uri_adapter
end

#write_timeout(value) ⇒ Object

Allows setting a default write_timeout for all HTTP calls in seconds Supported by Ruby > 2.6.0

class Foo
include HTTParty
write_timeout 10
end


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

def write_timeout(value)
  validate_timeout_argument(__method__, value)
  default_options[:write_timeout] = value
end