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.
-
#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.
576 577 578 |
# File 'lib/httparty.rb', line 576 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
110 111 112 113 |
# File 'lib/httparty.rb', line 110 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
121 122 123 |
# File 'lib/httparty.rb', line 121 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
411 412 413 |
# File 'lib/httparty.rb', line 411 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
486 487 488 489 490 491 492 493 |
# File 'lib/httparty.rb', line 486 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
244 245 246 247 |
# File 'lib/httparty.rb', line 244 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
548 549 550 |
# File 'lib/httparty.rb', line 548 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
224 225 226 |
# File 'lib/httparty.rb', line 224 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
164 165 166 167 168 |
# File 'lib/httparty.rb', line 164 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
177 178 179 180 |
# File 'lib/httparty.rb', line 177 def default_timeout(value) validate_timeout_argument(__method__, value) [:timeout] = value end |
#delete(path, options = {}, &block) ⇒ Object
Perform a DELETE request to a path
538 539 540 |
# File 'lib/httparty.rb', line 538 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
131 132 133 |
# File 'lib/httparty.rb', line 131 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
153 154 155 |
# File 'lib/httparty.rb', line 153 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.
258 259 260 |
# File 'lib/httparty.rb', line 258 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
269 270 271 272 273 274 275 276 277 |
# File 'lib/httparty.rb', line 269 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})
507 508 509 |
# File 'lib/httparty.rb', line 507 def get(path, = {}, &block) perform_request Net::HTTP::Get, path, , &block end |
#head(path, options = {}, &block) ⇒ Object
Perform a HEAD request to a path
553 554 555 556 |
# File 'lib/httparty.rb', line 553 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
234 235 236 237 238 239 240 241 242 |
# File 'lib/httparty.rb', line 234 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
96 97 98 99 100 101 |
# File 'lib/httparty.rb', line 96 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
568 569 570 |
# File 'lib/httparty.rb', line 568 def lock(path, = {}, &block) perform_request Net::HTTP::Lock, path, , &block end |
#logger(logger, level = :info, format = :apache) ⇒ Object
74 75 76 77 78 |
# File 'lib/httparty.rb', line 74 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.
315 316 317 |
# File 'lib/httparty.rb', line 315 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
564 565 566 |
# File 'lib/httparty.rb', line 564 def mkcol(path, = {}, &block) perform_request Net::HTTP::Mkcol, path, , &block end |
#move(path, options = {}, &block) ⇒ Object
Perform a MOVE request to a path
543 544 545 |
# File 'lib/httparty.rb', line 543 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.
298 299 300 |
# File 'lib/httparty.rb', line 298 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
188 189 190 191 |
# File 'lib/httparty.rb', line 188 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
559 560 561 |
# File 'lib/httparty.rb', line 559 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
451 452 453 454 455 456 457 458 |
# File 'lib/httparty.rb', line 451 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
528 529 530 |
# File 'lib/httparty.rb', line 528 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
343 344 345 346 |
# File 'lib/httparty.rb', line 343 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
354 355 356 357 |
# File 'lib/httparty.rb', line 354 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'})
523 524 525 |
# File 'lib/httparty.rb', line 523 def post(path, = {}, &block) perform_request Net::HTTP::Post, path, , &block end |
#put(path, options = {}, &block) ⇒ Object
Perform a PUT request to a path
533 534 535 |
# File 'lib/httparty.rb', line 533 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.
387 388 389 |
# File 'lib/httparty.rb', line 387 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
86 87 88 |
# File 'lib/httparty.rb', line 86 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
199 200 201 202 |
# File 'lib/httparty.rb', line 199 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.
333 334 335 |
# File 'lib/httparty.rb', line 333 def resend_on_redirect(value = true) [:resend_on_redirect] = 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
427 428 429 |
# File 'lib/httparty.rb', line 427 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
441 442 443 |
# File 'lib/httparty.rb', line 441 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
398 399 400 |
# File 'lib/httparty.rb', line 398 def ssl_version(version) [:ssl_version] = version end |
#unlock(path, options = {}, &block) ⇒ Object
572 573 574 |
# File 'lib/httparty.rb', line 572 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
466 467 468 469 |
# File 'lib/httparty.rb', line 466 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
211 212 213 214 |
# File 'lib/httparty.rb', line 211 def write_timeout(value) validate_timeout_argument(__method__, value) [:write_timeout] = value end |