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
: -
Allow for streaming large files without loading them into memory.
- :
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
-
#default_options ⇒ Object
readonly
Returns the value of attribute default_options.
Instance Method Summary collapse
-
#base_uri(uri = nil) ⇒ Object
Allows setting a base uri to be used for each request.
-
#basic_auth(u, p) ⇒ Object
Allows setting basic authentication username and password.
-
#ciphers(cipher_names) ⇒ Object
Allows setting of SSL ciphers to use.
-
#connection_adapter(custom_adapter = nil, options = nil) ⇒ Object
Allows setting a custom connection_adapter for the http connections.
- #cookies(h = {}) ⇒ Object
-
#copy(path, options = {}, &block) ⇒ Object
Perform a COPY request to a path.
-
#debug_output(stream = $stderr) ⇒ Object
Set an output stream for debugging, defaults to $stderr.
-
#default_params(h = {}) ⇒ Object
Allows setting default parameters to be appended to each request.
-
#default_timeout(value) ⇒ Object
Allows setting a default timeout for all HTTP calls Timeout is specified in seconds.
-
#delete(path, options = {}, &block) ⇒ Object
Perform a DELETE request to a path.
-
#digest_auth(u, p) ⇒ Object
Allows setting digest authentication username and password.
-
#disable_rails_query_string_format ⇒ Object
Do not send rails style query strings.
-
#follow_redirects(value = true) ⇒ Object
Proceed to the location header when an HTTP response dictates a redirect.
-
#format(f = nil) ⇒ Object
Allows setting the format with which to parse.
-
#get(path, options = {}, &block) ⇒ Object
Allows making a get request to a url.
-
#head(path, options = {}, &block) ⇒ Object
Perform a HEAD request to a path.
-
#headers(h = nil) ⇒ Object
Allows setting HTTP headers to be used for each request.
-
#http_proxy(addr = nil, port = nil, user = nil, pass = nil) ⇒ Object
Allows setting http proxy information to be used.
- #lock(path, options = {}, &block) ⇒ Object
-
#logger(logger, level = :info, format = :apache) ⇒ Object
Turns on logging.
-
#maintain_method_across_redirects(value = true) ⇒ Object
Declare that you wish to maintain the chosen HTTP method across redirects.
-
#mkcol(path, options = {}, &block) ⇒ Object
Perform a MKCOL request to a path.
-
#move(path, options = {}, &block) ⇒ Object
Perform a MOVE request to a path.
-
#no_follow(value = false) ⇒ Object
Declare whether or not to follow redirects.
-
#open_timeout(value) ⇒ Object
Allows setting a default open_timeout for all HTTP calls in seconds.
-
#options(path, options = {}, &block) ⇒ Object
Perform an OPTIONS request to a path.
-
#parser(custom_parser = nil) ⇒ Object
Allows setting a custom parser for the response.
-
#patch(path, options = {}, &block) ⇒ Object
Perform a PATCH request to a path.
-
#pem(pem_contents, password = nil) ⇒ Object
Allows setting a PEM file to be used.
-
#pkcs12(p12_contents, password) ⇒ Object
Allows setting a PKCS12 file to be used.
-
#post(path, options = {}, &block) ⇒ Object
Allows making a post request to a url.
-
#put(path, options = {}, &block) ⇒ Object
Perform a PUT request to a path.
-
#query_string_normalizer(normalizer) {|Hash, String| ... } ⇒ Object
Override the way query strings are normalized.
-
#raise_on(codes = []) ⇒ Object
Raises HTTParty::ResponseError if response’s code matches this statuses.
-
#read_timeout(value) ⇒ Object
Allows setting a default read_timeout for all HTTP calls in seconds.
-
#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.
-
#skip_decompression(value = true) ⇒ Object
Deactivate automatic decompression of the response body.
-
#ssl_ca_file(path) ⇒ Object
Allows setting an OpenSSL certificate authority file.
-
#ssl_ca_path(path) ⇒ Object
Allows setting an OpenSSL certificate authority path (directory).
-
#ssl_version(version) ⇒ Object
Allows setting of SSL version to use.
- #unlock(path, options = {}, &block) ⇒ Object
-
#uri_adapter(uri_adapter) ⇒ Object
Allows setting a custom URI adapter.
-
#write_timeout(value) ⇒ Object
Allows setting a default write_timeout for all HTTP calls in seconds Supported by Ruby > 2.6.0.
Instance Attribute Details
#default_options ⇒ Object (readonly)
Returns the value of attribute default_options.
595 596 597 |
# File 'lib/httparty.rb', line 595 def @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
113 114 115 116 |
# File 'lib/httparty.rb', line 113 def base_uri(uri = nil) return [:base_uri] unless uri [: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
124 125 126 |
# File 'lib/httparty.rb', line 124 def basic_auth(u, p) [:basic_auth] = {username: u, password: p} 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: www.openssl.org/docs/apps/ciphers.html#CIPHER_SUITE_NAMES
class Foo
include HTTParty
ciphers "RC4-SHA"
end
430 431 432 |
# File 'lib/httparty.rb', line 430 def ciphers(cipher_names) [:ciphers] = cipher_names end |
#connection_adapter(custom_adapter = nil, options = nil) ⇒ Object
Allows setting a custom connection_adapter for the http connections
505 506 507 508 509 510 511 512 |
# File 'lib/httparty.rb', line 505 def connection_adapter(custom_adapter = nil, = nil) if custom_adapter.nil? [:connection_adapter] else [:connection_adapter] = custom_adapter [:connection_adapter_options] = end end |
#cookies(h = {}) ⇒ Object
247 248 249 250 |
# File 'lib/httparty.rb', line 247 def (h = {}) raise ArgumentError, 'Cookies must be an object which responds to #to_hash' unless h.respond_to?(:to_hash) .(h) end |
#copy(path, options = {}, &block) ⇒ Object
Perform a COPY request to a path
567 568 569 |
# File 'lib/httparty.rb', line 567 def copy(path, = {}, &block) perform_request Net::HTTP::Copy, path, , &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
227 228 229 |
# File 'lib/httparty.rb', line 227 def debug_output(stream = $stderr) [: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
167 168 169 170 171 |
# File 'lib/httparty.rb', line 167 def default_params(h = {}) raise ArgumentError, 'Default params must be an object which responds to #to_hash' unless h.respond_to?(:to_hash) [:default_params] ||= {} [: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
180 181 182 183 |
# File 'lib/httparty.rb', line 180 def default_timeout(value) validate_timeout_argument(__method__, value) [:timeout] = value end |
#delete(path, options = {}, &block) ⇒ Object
Perform a DELETE request to a path
557 558 559 |
# File 'lib/httparty.rb', line 557 def delete(path, = {}, &block) perform_request Net::HTTP::Delete, path, , &block end |
#digest_auth(u, p) ⇒ Object
Allows setting digest authentication username and password.
class Foo
include HTTParty
digest_auth 'username', 'password'
end
134 135 136 |
# File 'lib/httparty.rb', line 134 def digest_auth(u, p) [: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
156 157 158 |
# File 'lib/httparty.rb', line 156 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.
261 262 263 |
# File 'lib/httparty.rb', line 261 def follow_redirects(value = true) [: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
272 273 274 275 276 277 278 279 280 |
# File 'lib/httparty.rb', line 272 def format(f = nil) if f.nil? [:format] else parser(Parser) if parser.nil? [:format] = f validate_format end 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})
526 527 528 |
# File 'lib/httparty.rb', line 526 def get(path, = {}, &block) perform_request Net::HTTP::Get, path, , &block end |
#head(path, options = {}, &block) ⇒ Object
Perform a HEAD request to a path
572 573 574 575 |
# File 'lib/httparty.rb', line 572 def head(path, = {}, &block) ensure_method_maintained_across_redirects perform_request Net::HTTP::Head, path, , &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
237 238 239 240 241 242 243 244 245 |
# File 'lib/httparty.rb', line 237 def headers(h = nil) if h raise ArgumentError, 'Headers must be an object which responds to #to_hash' unless h.respond_to?(:to_hash) [:headers] ||= {} [:headers].merge!(h.to_hash) else [: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
99 100 101 102 103 104 |
# File 'lib/httparty.rb', line 99 def http_proxy(addr = nil, port = nil, user = nil, pass = nil) [:http_proxyaddr] = addr [:http_proxyport] = port [:http_proxyuser] = user [:http_proxypass] = pass end |
#lock(path, options = {}, &block) ⇒ Object
587 588 589 |
# File 'lib/httparty.rb', line 587 def lock(path, = {}, &block) perform_request Net::HTTP::Lock, path, , &block end |
#logger(logger, level = :info, format = :apache) ⇒ Object
77 78 79 80 81 |
# File 'lib/httparty.rb', line 77 def logger(logger, level = :info, format = :apache) [:logger] = logger [:log_level] = level [: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.
318 319 320 |
# File 'lib/httparty.rb', line 318 def maintain_method_across_redirects(value = true) [:maintain_method_across_redirects] = value end |
#mkcol(path, options = {}, &block) ⇒ Object
Perform a MKCOL request to a path
583 584 585 |
# File 'lib/httparty.rb', line 583 def mkcol(path, = {}, &block) perform_request Net::HTTP::Mkcol, path, , &block end |
#move(path, options = {}, &block) ⇒ Object
Perform a MOVE request to a path
562 563 564 |
# File 'lib/httparty.rb', line 562 def move(path, = {}, &block) perform_request Net::HTTP::Move, path, , &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.
301 302 303 |
# File 'lib/httparty.rb', line 301 def no_follow(value = false) [: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
191 192 193 194 |
# File 'lib/httparty.rb', line 191 def open_timeout(value) validate_timeout_argument(__method__, value) [:open_timeout] = value end |
#options(path, options = {}, &block) ⇒ Object
Perform an OPTIONS request to a path
578 579 580 |
# File 'lib/httparty.rb', line 578 def (path, = {}, &block) perform_request Net::HTTP::Options, path, , &block end |
#parser(custom_parser = nil) ⇒ Object
Allows setting a custom parser for the response.
class Foo
include HTTParty
parser Proc.new {|data| ...}
end
470 471 472 473 474 475 476 477 |
# File 'lib/httparty.rb', line 470 def parser(custom_parser = nil) if custom_parser.nil? [:parser] else [:parser] = custom_parser validate_format end end |
#patch(path, options = {}, &block) ⇒ Object
Perform a PATCH request to a path
547 548 549 |
# File 'lib/httparty.rb', line 547 def patch(path, = {}, &block) perform_request Net::HTTP::Patch, path, , &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
346 347 348 349 |
# File 'lib/httparty.rb', line 346 def pem(pem_contents, password = nil) [:pem] = pem_contents [: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
357 358 359 360 |
# File 'lib/httparty.rb', line 357 def pkcs12(p12_contents, password) [:p12] = p12_contents [: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'})
542 543 544 |
# File 'lib/httparty.rb', line 542 def post(path, = {}, &block) perform_request Net::HTTP::Post, path, , &block end |
#put(path, options = {}, &block) ⇒ Object
Perform a PUT request to a path
552 553 554 |
# File 'lib/httparty.rb', line 552 def put(path, = {}, &block) perform_request Net::HTTP::Put, path, , &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.
390 391 392 |
# File 'lib/httparty.rb', line 390 def query_string_normalizer(normalizer) [:query_string_normalizer] = normalizer end |
#raise_on(codes = []) ⇒ Object
Raises HTTParty::ResponseError if response’s code matches this statuses
class Foo
include HTTParty
raise_on [404, 500]
end
89 90 91 |
# File 'lib/httparty.rb', line 89 def raise_on(codes = []) [:raise_on] = *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
202 203 204 205 |
# File 'lib/httparty.rb', line 202 def read_timeout(value) validate_timeout_argument(__method__, value) [: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.
336 337 338 |
# File 'lib/httparty.rb', line 336 def resend_on_redirect(value = true) [: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.
417 418 419 |
# File 'lib/httparty.rb', line 417 def skip_decompression(value = true) [: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
446 447 448 |
# File 'lib/httparty.rb', line 446 def ssl_ca_file(path) [: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
460 461 462 |
# File 'lib/httparty.rb', line 460 def ssl_ca_path(path) [: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
401 402 403 |
# File 'lib/httparty.rb', line 401 def ssl_version(version) [:ssl_version] = version end |
#unlock(path, options = {}, &block) ⇒ Object
591 592 593 |
# File 'lib/httparty.rb', line 591 def unlock(path, = {}, &block) perform_request Net::HTTP::Unlock, path, , &block end |
#uri_adapter(uri_adapter) ⇒ Object
Allows setting a custom URI adapter.
class Foo
include HTTParty
uri_adapter Addressable::URI
end
485 486 487 488 |
# File 'lib/httparty.rb', line 485 def uri_adapter(uri_adapter) raise ArgumentError, 'The URI adapter should respond to #parse' unless uri_adapter.respond_to?(:parse) [: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
214 215 216 217 |
# File 'lib/httparty.rb', line 214 def write_timeout(value) validate_timeout_argument(__method__, value) [:write_timeout] = value end |