Module: HTTParty::ClassMethods
- Extended by:
- AllowedFormatsDeprecation
- Defined in:
- lib/httparty.rb
Overview
Common Request Options
Request methods (get, post, 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.
- :
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.
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. -
:
pem
: see HTTParty::ClassMethods.pem. -
:
query_string_normalizer
: see HTTParty::ClassMethods.query_string_normalizer -
:
ssl_ca_file
: see HTTParty::ClassMethods.ssl_ca_file.
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.
- #cookies(h = {}) ⇒ Object
-
#debug_output(stream = $stderr) ⇒ Object
Set an output stream for debugging, defaults to $stderr.
-
#default_options ⇒ Object
:nodoc:.
-
#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 = {}) ⇒ 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 = {}) ⇒ Object
Allows making a get request to a url.
-
#head(path, options = {}) ⇒ Object
Perform a HEAD request to a path.
-
#headers(h = {}) ⇒ Object
Allows setting HTTP headers to be used for each request.
-
#http_proxy(addr = nil, port = nil) ⇒ Object
Allows setting http proxy information to be used.
-
#maintain_method_across_redirects(value = true) ⇒ Object
Declare that you wish to maintain the chosen HTTP method across redirects.
-
#no_follow(value = false) ⇒ Object
Declare whether or not to follow redirects.
-
#options(path, options = {}) ⇒ Object
Perform an OPTIONS request to a path.
-
#parser(custom_parser = nil) ⇒ Object
Allows setting a custom parser for the response.
-
#pem(pem_contents, password = nil) ⇒ Object
Allows setting a PEM file to be used.
-
#post(path, options = {}) ⇒ Object
Allows making a post request to a url.
-
#put(path, options = {}) ⇒ Object
Perform a PUT request to a path.
-
#query_string_normalizer(normalizer) {|Hash, String| ... } ⇒ Object
Override the way query strings are normalized.
-
#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).
Methods included from AllowedFormatsDeprecation
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
87 88 89 90 |
# File 'lib/httparty.rb', line 87 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
98 99 100 |
# File 'lib/httparty.rb', line 98 def basic_auth(u, p) [:basic_auth] = {:username => u, :password => p} end |
#cookies(h = {}) ⇒ Object
182 183 184 185 |
# File 'lib/httparty.rb', line 182 def (h={}) raise ArgumentError, 'Cookies must be a hash' unless h.is_a?(Hash) .(h) 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
166 167 168 |
# File 'lib/httparty.rb', line 166 def debug_output(stream = $stderr) [:debug_output] = stream end |
#default_options ⇒ Object
:nodoc:
385 386 387 |
# File 'lib/httparty.rb', line 385 def #:nodoc: @default_options 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
141 142 143 144 145 |
# File 'lib/httparty.rb', line 141 def default_params(h={}) raise ArgumentError, 'Default params must be a hash' unless h.is_a?(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
154 155 156 157 |
# File 'lib/httparty.rb', line 154 def default_timeout(t) raise ArgumentError, 'Timeout must be an integer' unless t && t.is_a?(Integer) [:timeout] = t end |
#delete(path, options = {}) ⇒ Object
Perform a DELETE request to a path
371 372 373 |
# File 'lib/httparty.rb', line 371 def delete(path, ={}) perform_request Net::HTTP::Delete, path, end |
#digest_auth(u, p) ⇒ Object
Allows setting digest authentication username and password.
class Foo
include HTTParty
digest_auth 'username', 'password'
end
108 109 110 |
# File 'lib/httparty.rb', line 108 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. 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
130 131 132 |
# File 'lib/httparty.rb', line 130 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.
196 197 198 |
# File 'lib/httparty.rb', line 196 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
207 208 209 210 211 212 213 214 215 |
# File 'lib/httparty.rb', line 207 def format(f = nil) if f.nil? [:format] else parser(Parser) if parser.nil? [:format] = f validate_format end end |
#get(path, options = {}) ⇒ 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})
345 346 347 |
# File 'lib/httparty.rb', line 345 def get(path, ={}) perform_request Net::HTTP::Get, path, end |
#head(path, options = {}) ⇒ Object
Perform a HEAD request to a path
376 377 378 |
# File 'lib/httparty.rb', line 376 def head(path, ={}) perform_request Net::HTTP::Head, path, end |
#headers(h = {}) ⇒ Object
Allows setting HTTP headers to be used for each request.
class Foo
include HTTParty
headers 'Accept' => 'text/html'
end
176 177 178 179 180 |
# File 'lib/httparty.rb', line 176 def headers(h={}) raise ArgumentError, 'Headers must be a hash' unless h.is_a?(Hash) [:headers] ||= {} [:headers].merge!(h) end |
#http_proxy(addr = nil, port = nil) ⇒ Object
Allows setting http proxy information to be used
class Foo
include HTTParty
http_proxy 'http://foo.com', 80
end
75 76 77 78 |
# File 'lib/httparty.rb', line 75 def http_proxy(addr=nil, port = nil) [:http_proxyaddr] = addr [:http_proxyport] = port 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. If you wish to maintain the original method, you can set this option to true.
251 252 253 |
# File 'lib/httparty.rb', line 251 def maintain_method_across_redirects(value = true) [:maintain_method_across_redirects] = value 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.
236 237 238 |
# File 'lib/httparty.rb', line 236 def no_follow(value = false) [:no_follow] = value end |
#options(path, options = {}) ⇒ Object
Perform an OPTIONS request to a path
381 382 383 |
# File 'lib/httparty.rb', line 381 def (path, ={}) perform_request Net::HTTP::Options, path, end |
#parser(custom_parser = nil) ⇒ Object
Allows setting a custom parser for the response.
class Foo
include HTTParty
parser Proc.new {|data| ...}
end
324 325 326 327 328 329 330 331 |
# File 'lib/httparty.rb', line 324 def parser(custom_parser = nil) if custom_parser.nil? [:parser] else [:parser] = custom_parser validate_format end 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
261 262 263 264 |
# File 'lib/httparty.rb', line 261 def pem(pem_contents, password=nil) [:pem] = pem_contents [:pem_password] = password end |
#post(path, options = {}) ⇒ 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 gets set as form data on the request.
Foo.post('http://foo.com/resources', :query => {:bar => 'baz'})
361 362 363 |
# File 'lib/httparty.rb', line 361 def post(path, ={}) perform_request Net::HTTP::Post, path, end |
#put(path, options = {}) ⇒ Object
Perform a PUT request to a path
366 367 368 |
# File 'lib/httparty.rb', line 366 def put(path, ={}) perform_request Net::HTTP::Put, path, 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.
294 295 296 |
# File 'lib/httparty.rb', line 294 def query_string_normalizer(normalizer) [:query_string_normalizer] = normalizer end |
#ssl_ca_file(path) ⇒ Object
Allows setting an OpenSSL certificate authority file
class Foo
include HTTParty
ssl_ca_file '/etc/ssl/certs/ca-certificates.crt'
end
304 305 306 |
# File 'lib/httparty.rb', line 304 def ssl_ca_file(path) [:ssl_ca_file] = path end |
#ssl_ca_path(path) ⇒ Object
Allows setting an OpenSSL certificate authority path (directory)
class Foo
include HTTParty
ssl_ca_path '/etc/ssl/certs/'
end
314 315 316 |
# File 'lib/httparty.rb', line 314 def ssl_ca_path(path) [:ssl_ca_path] = path end |