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(t) ⇒ 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(t) ⇒ 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(t) ⇒ 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.
Instance Attribute Details
#default_options ⇒ Object (readonly)
Returns the value of attribute default_options.
559 560 561 |
# File 'lib/httparty.rb', line 559 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
106 107 108 109 |
# File 'lib/httparty.rb', line 106 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
117 118 119 |
# File 'lib/httparty.rb', line 117 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
394 395 396 |
# File 'lib/httparty.rb', line 394 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
469 470 471 472 473 474 475 476 |
# File 'lib/httparty.rb', line 469 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
227 228 229 230 |
# File 'lib/httparty.rb', line 227 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
531 532 533 |
# File 'lib/httparty.rb', line 531 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
207 208 209 |
# File 'lib/httparty.rb', line 207 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
160 161 162 163 164 |
# File 'lib/httparty.rb', line 160 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(t) ⇒ Object
Allows setting a default timeout for all HTTP calls Timeout is specified in seconds.
class Foo
include HTTParty
default_timeout 10
end
173 174 175 176 |
# File 'lib/httparty.rb', line 173 def default_timeout(t) raise ArgumentError, 'Timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float)) [:timeout] = t end |
#delete(path, options = {}, &block) ⇒ Object
Perform a DELETE request to a path
521 522 523 |
# File 'lib/httparty.rb', line 521 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
127 128 129 |
# File 'lib/httparty.rb', line 127 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
149 150 151 |
# File 'lib/httparty.rb', line 149 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.
241 242 243 |
# File 'lib/httparty.rb', line 241 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
252 253 254 255 256 257 258 259 260 |
# File 'lib/httparty.rb', line 252 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})
490 491 492 |
# File 'lib/httparty.rb', line 490 def get(path, = {}, &block) perform_request Net::HTTP::Get, path, , &block end |
#head(path, options = {}, &block) ⇒ Object
Perform a HEAD request to a path
536 537 538 539 |
# File 'lib/httparty.rb', line 536 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
217 218 219 220 221 222 223 224 225 |
# File 'lib/httparty.rb', line 217 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
92 93 94 95 96 97 |
# File 'lib/httparty.rb', line 92 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
551 552 553 |
# File 'lib/httparty.rb', line 551 def lock(path, = {}, &block) perform_request Net::HTTP::Lock, path, , &block end |
#logger(logger, level = :info, format = :apache) ⇒ Object
70 71 72 73 74 |
# File 'lib/httparty.rb', line 70 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.
298 299 300 |
# File 'lib/httparty.rb', line 298 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
547 548 549 |
# File 'lib/httparty.rb', line 547 def mkcol(path, = {}, &block) perform_request Net::HTTP::Mkcol, path, , &block end |
#move(path, options = {}, &block) ⇒ Object
Perform a MOVE request to a path
526 527 528 |
# File 'lib/httparty.rb', line 526 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.
281 282 283 |
# File 'lib/httparty.rb', line 281 def no_follow(value = false) [:no_follow] = value end |
#open_timeout(t) ⇒ Object
Allows setting a default open_timeout for all HTTP calls in seconds
class Foo
include HTTParty
open_timeout 10
end
184 185 186 187 |
# File 'lib/httparty.rb', line 184 def open_timeout(t) raise ArgumentError, 'open_timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float)) [:open_timeout] = t end |
#options(path, options = {}, &block) ⇒ Object
Perform an OPTIONS request to a path
542 543 544 |
# File 'lib/httparty.rb', line 542 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
434 435 436 437 438 439 440 441 |
# File 'lib/httparty.rb', line 434 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
511 512 513 |
# File 'lib/httparty.rb', line 511 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
326 327 328 329 |
# File 'lib/httparty.rb', line 326 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
337 338 339 340 |
# File 'lib/httparty.rb', line 337 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'})
506 507 508 |
# File 'lib/httparty.rb', line 506 def post(path, = {}, &block) perform_request Net::HTTP::Post, path, , &block end |
#put(path, options = {}, &block) ⇒ Object
Perform a PUT request to a path
516 517 518 |
# File 'lib/httparty.rb', line 516 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.
370 371 372 |
# File 'lib/httparty.rb', line 370 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
82 83 84 |
# File 'lib/httparty.rb', line 82 def raise_on(codes = []) [:raise_on] = *codes end |
#read_timeout(t) ⇒ Object
Allows setting a default read_timeout for all HTTP calls in seconds
class Foo
include HTTParty
read_timeout 10
end
195 196 197 198 |
# File 'lib/httparty.rb', line 195 def read_timeout(t) raise ArgumentError, 'read_timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float)) [:read_timeout] = t 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.
316 317 318 |
# File 'lib/httparty.rb', line 316 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
410 411 412 |
# File 'lib/httparty.rb', line 410 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
424 425 426 |
# File 'lib/httparty.rb', line 424 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
381 382 383 |
# File 'lib/httparty.rb', line 381 def ssl_version(version) [:ssl_version] = version end |
#unlock(path, options = {}, &block) ⇒ Object
555 556 557 |
# File 'lib/httparty.rb', line 555 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
449 450 451 452 |
# File 'lib/httparty.rb', line 449 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 |