module HTTParty::ClassMethods
def base_uri(uri = nil)
base_uri 'twitter.com'
include HTTParty
class Foo
Will normalize uri to include http, etc.
Allows setting a base uri to be used for each request.
def base_uri(uri = nil) return default_options[:base_uri] unless uri default_options[:base_uri] = HTTParty.normalize_base_uri(uri) end
def basic_auth(u, p)
basic_auth 'username', 'password'
include HTTParty
class Foo
Allows setting basic authentication username and password.
def basic_auth(u, p) default_options[:basic_auth] = {username: u, password: p} end
def ciphers(cipher_names)
ciphers "RC4-SHA"
include HTTParty
class Foo
http://www.openssl.org/docs/apps/ciphers.html#CIPHER_SUITE_NAMES
You also can specify a cipher suite here, listed here at openssl.org:
You can get a list of valid specific ciphers from OpenSSL::Cipher.ciphers.
Allows setting of SSL ciphers to use. This only works in Ruby 1.9+.
def ciphers(cipher_names) default_options[:ciphers] = cipher_names end
def connection_adapter(custom_adapter = nil, options = nil)
- See: HTTParty::ConnectionAdapter -
Other tags:
- Example: provide optional configuration for your connection_adapter -
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
def cookies(h = {})
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
def copy(path, options = {}, &block)
def copy(path, options = {}, &block) perform_request Net::HTTP::Copy, path, options, &block end
def debug_output(stream = $stderr)
debug_output $stderr
include HTTParty
class Foo
The output stream is passed on to Net::HTTP#set_debug_output.
Set an output stream for debugging, defaults to $stderr.
def debug_output(stream = $stderr) default_options[:debug_output] = stream end
def default_params(h = {})
default_params api_key: 'secret', another: 'foo'
include HTTParty
class Foo
Great for api keys and such.
Allows setting default parameters to be appended to each request.
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
def default_timeout(t)
default_timeout 10
include HTTParty
class Foo
Timeout is specified in seconds.
Allows setting a default timeout for all HTTP calls
def default_timeout(t) raise ArgumentError, 'Timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float)) default_options[:timeout] = t end
def delete(path, options = {}, &block)
def delete(path, options = {}, &block) perform_request Net::HTTP::Delete, path, options, &block end
def digest_auth(u, p)
digest_auth 'username', 'password'
include HTTParty
class Foo
Allows setting digest authentication username and password.
def digest_auth(u, p) default_options[:digest_auth] = {username: u, password: p} end
def disable_rails_query_string_format
disable_rails_query_string_format
include HTTParty
class Foo
@example
/?selected_ids=1&selected_ids=2&selected_ids=3
into:
Call `disable_rails_query_string_format` to transform the query string
/?selected_ids[]=1&selected_ids[]=2&selected_ids[]=3
The default query string looks like this:
get '/', query: {selected_ids: [1,2,3]}
For a query:
Specifically, don't use bracket notation when sending an array
Do not send rails style query strings.
def disable_rails_query_string_format query_string_normalizer Request::NON_RAILS_QUERY_STRING_NORMALIZER end
def ensure_method_maintained_across_redirects(options)
def ensure_method_maintained_across_redirects(options) unless options.key?(:maintain_method_across_redirects) options[:maintain_method_across_redirects] = true end end
def follow_redirects(value = true)
follow_redirects true
base_uri 'http://google.com'
include HTTParty
class Foo
@example
Redirects are always followed by default.
Proceed to the location header when an HTTP response dictates a redirect.
def follow_redirects(value = true) default_options[:follow_redirects] = value end
def format(f = nil)
format :json
include HTTParty
class Foo
Must be one of the allowed formats ie: json, xml
Allows setting the format with which to parse.
def format(f = nil) if f.nil? default_options[:format] else parser(Parser) if parser.nil? default_options[:format] = f validate_format end end
def get(path, options = {}, &block)
# ie: http://foo.com/resource.json?limit=10
# Simple get with full url and query parameters
Foo.get('http://foo.com/resource.json')
# Simple get with full url
end
include HTTParty
class Foo
Allows making a get request to a url.
def get(path, options = {}, &block) perform_request Net::HTTP::Get, path, options, &block end
def head(path, options = {}, &block)
def head(path, options = {}, &block) ensure_method_maintained_across_redirects options perform_request Net::HTTP::Head, path, options, &block end
def headers(h = nil)
headers 'Accept' => 'text/html'
include HTTParty
class Foo
Allows setting HTTP headers to be used for each request.
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
def http_proxy(addr = nil, port = nil, user = nil, pass = nil)
http_proxy 'http://foo.com', 80, 'user', 'pass'
include HTTParty
class Foo
Allows setting http proxy information to be used
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
def logger(logger, level = :info, format = :apache)
logger Logger.new('http_logger'), :info, :apache
include HTTParty
class Foo
Turns on logging
def logger(logger, level = :info, format = :apache) default_options[:logger] = logger default_options[:log_level] = level default_options[:log_format] = format end
def maintain_method_across_redirects(value = true)
def maintain_method_across_redirects(value = true) default_options[:maintain_method_across_redirects] = value end
def mkcol(path, options = {}, &block)
def mkcol(path, options = {}, &block) perform_request Net::HTTP::Mkcol, path, options, &block end
def move(path, options = {}, &block)
def move(path, options = {}, &block) perform_request Net::HTTP::Move, path, options, &block end
def no_follow(value = false)
- See: HTTParty::ResponseError#response -
def no_follow(value = false) default_options[:no_follow] = value end
def open_timeout(t)
open_timeout 10
include HTTParty
class Foo
Allows setting a default open_timeout for all HTTP calls in seconds
def open_timeout(t) raise ArgumentError, 'open_timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float)) default_options[:open_timeout] = t end
def options(path, options = {}, &block)
def options(path, options = {}, &block) perform_request Net::HTTP::Options, path, options, &block end
def parser(custom_parser = nil)
parser Proc.new {|data| ...}
include HTTParty
class Foo
Allows setting a custom parser for the response.
def parser(custom_parser = nil) if custom_parser.nil? default_options[:parser] else default_options[:parser] = custom_parser validate_format end end
def patch(path, options = {}, &block)
def patch(path, options = {}, &block) perform_request Net::HTTP::Patch, path, options, &block end
def pem(pem_contents, password = nil)
pem File.read('/home/user/my.pem'), "optional password"
include HTTParty
class Foo
Allows setting a PEM file to be used
def pem(pem_contents, password = nil) default_options[:pem] = pem_contents default_options[:pem_password] = password end
def perform_request(http_method, path, options, &block) #:nodoc:
def perform_request(http_method, path, options, &block) #:nodoc: options = ModuleInheritableAttributes.hash_deep_dup(default_options).merge(options) process_headers(options) process_cookies(options) Request.new(http_method, path, options).perform(&block) end
def pkcs12(p12_contents, password)
pkcs12 File.read('/home/user/my.p12'), "password"
include HTTParty
class Foo
Allows setting a PKCS12 file to be used
def pkcs12(p12_contents, password) default_options[:p12] = p12_contents default_options[:p12_password] = password end
def post(path, options = {}, &block)
# which appends the parameters to the URI.
# Simple post with full url using :query option,
Foo.post('http://foo.com/resources', body: {bar: 'baz'})
# Simple post with full url and setting the body
end
include HTTParty
class Foo
Allows making a post request to a url.
def post(path, options = {}, &block) perform_request Net::HTTP::Post, path, options, &block end
def process_cookies(options) #:nodoc:
def process_cookies(options) #:nodoc: return unless options[:cookies] || default_cookies.any? options[:headers] ||= headers.dup options[:headers]["cookie"] = cookies.merge(options.delete(:cookies) || {}).to_cookie_string end
def process_headers(options)
def process_headers(options) if options[:headers] && headers.any? options[:headers] = headers.merge(options[:headers]) end end
def put(path, options = {}, &block)
def put(path, options = {}, &block) perform_request Net::HTTP::Put, path, options, &block end
def query_string_normalizer(normalizer)
- Yieldreturn: - an array that will later be joined with '&'
Other tags:
- Yield: - query string
Parameters:
-
normalizer
(Proc
) -- custom query string normalizer.
Other tags:
- Example: Modifying Array query strings -
def query_string_normalizer(normalizer) default_options[:query_string_normalizer] = normalizer end
def raise_on(codes = [])
raise_on [404, 500]
include HTTParty
class Foo
Raises HTTParty::ResponseError if response's code matches this statuses
def raise_on(codes = []) default_options[:raise_on] = *codes end
def read_timeout(t)
read_timeout 10
include HTTParty
class Foo
Allows setting a default read_timeout for all HTTP calls in seconds
def read_timeout(t) raise ArgumentError, 'read_timeout must be an integer or float' unless t && (t.is_a?(Integer) || t.is_a?(Float)) default_options[:read_timeout] = t end
def resend_on_redirect(value = true)
def resend_on_redirect(value = true) default_options[:resend_on_redirect] = value end
def ssl_ca_file(path)
ssl_ca_file '/etc/ssl/certs/ca-certificates.crt'
include HTTParty
class Foo
ssl_ca_path for verification to succeed.
certificates along a chain must be available in ssl_ca_file or
Setting this option enables certificate verification. All
should contain one or more certificates in PEM format.
Allows setting an OpenSSL certificate authority file. The file
def ssl_ca_file(path) default_options[:ssl_ca_file] = path end
def ssl_ca_path(path)
ssl_ca_path '/etc/ssl/certs/'
include HTTParty
class Foo
ssl_ca_path for verification to succeed.
certificates along a chain must be available in ssl_ca_file or
Setting this option enables certificate verification. All
Allows setting an OpenSSL certificate authority path (directory).
def ssl_ca_path(path) default_options[:ssl_ca_path] = path end
def ssl_version(version)
ssl_version :SSLv3
include HTTParty
class Foo
You can get a list of valid versions from OpenSSL::SSL::SSLContext::METHODS.
Allows setting of SSL version to use. This only works in Ruby 1.9+.
def ssl_version(version) default_options[:ssl_version] = version end
def uri_adapter(uri_adapter)
uri_adapter Addressable::URI
include HTTParty
class Foo
Allows setting a custom URI adapter.
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
def validate_format
def validate_format if format && parser.respond_to?(:supports_format?) && !parser.supports_format?(format) raise UnsupportedFormat, "'#{format.inspect}' Must be one of: #{parser.supported_formats.map(&:to_s).sort.join(', ')}" end end