HTTPI provides a common interface for Ruby HTTP libraries.
The gem is available through Rubygems and can be installed via:
$ gem install httpi
Executing a POST request with the most basic request object:
request = HTTPI::Request.new "http://example.com"
HTTPI.get request
Here's a POST request with a request object:
request = HTTPI::Request.new
request.url = "http://post.example.com"
request.body = "send me"
HTTPI.post request
And a GET request using HTTP basic auth and the Curb adapter:
request = HTTPI::Request.new
request.url = "http://auth.example.com"
request.auth.basic "username", "password"
HTTPI.get request, :curb
HTTPI also comes shortcuts. This executes a PUT request:
HTTPI.put "http://example.com", "<some>xml</some>"
And this executes a DELETE request:
HTTPI.delete "http://example.com"
The HTTPI
module uses one of the available adapters to execute HTTP requests.
HTTPI.get(request, adapter = nil)
HTTPI.get(url, adapter = nil)
HTTPI.post(request, adapter = nil)
HTTPI.post(url, body, adapter = nil)
HTTPI.head(request, adapter = nil)
HTTPI.head(url, adapter = nil)
HTTPI.put(request, adapter = nil)
HTTPI.put(url, body, adapter = nil)
HTTPI.delete(request, adapter = nil)
HTTPI.delete(url, adapter = nil)
- You can specify the adapter to use per request
- And request methods always return an
HTTPI::Response
If you need more control over the request, you can access the HTTP client instance represented by your adapter in a block:
HTTPI.post request do |http|
http.use_ssl = true # Curb example
end
HTTPI uses adapters to support multiple HTTP libraries. It currently contains adapters for:
- httpclient ~> 2.1.5
- curb ~> 0.7.8
- net/http
You can manually specify the adapter to use via:
HTTPI::Adapter.use = :curb # or one of [:httpclient, :net_http]
If you don't specify which adapter to use, HTTPI try to load HTTPClient, then Curb and finally NetHTTP.
Notice: HTTPI does not force you to install any of these libraries. If you'd like to use on of the more advanced libraries (HTTPClient or Curb), you have to make sure they're in your LOAD_PATH. HTTPI will then load the library when executing HTTP requests.
The HTTPI::Request
serves as a common denominator of options that HTTPI adapters need to support.
It represents an HTTP request and lets you customize various settings through the following methods:
#url # the URL to access
#proxy # the proxy server to use
#ssl # whether to use SSL
#headers # a Hash of HTTP headers
#body # the HTTP request body
#open_timeout # the open timeout (sec)
#read_timeout # the read timeout (sec)
request = HTTPI::Request.new
request.url = "http://example.com"
request.read_timeout = 30
HTTPI::Auth
supports HTTP basic and digest authentication.
#basic(username, password) # HTTP basic auth credentials
#digest(username, password) # HTTP digest auth credentials
#ntlm(username, password) # NTLM auth credentials
request = HTTPI::Request.new
request.auth.basic "username", "password"
HTTPI::Auth::SSL
manages SSL client authentication.
#cert_key_file # the private key file to use
#cert_file # the certificate file to use
#ca_cert_file # the ca certificate file to use
#verify_mode # one of [:none, :peer, :fail_if_no_peer_cert, :client_once]
request = HTTPI::Request.new
request.auth.ssl.cert_key_file = "client_key.pem"
request.auth.ssl.cert_key_password = "C3rtP@ssw0rd"
request.auth.ssl.cert_file = "client_cert.pem"
request.auth.ssl.verify_mode = :none
As mentioned before, every request method return an HTTPI::Response
.
It contains the response code, headers and body.
response = HTTPI.get request
response.code # => 200
response.headers # => { "Content-Encoding" => "gzip" }
response.body # => "<!DOCTYPE HTML PUBLIC ...>"
The response.body
handles gzipped and DIME encoded responses.
- Return the original
HTTPI::Request
for debugging purposes - Return the time it took to execute the request
HTTPI by default logs each HTTP request to STDOUT using a log level of :debug.
HTTPI.log = false # disabling logging
HTTPI.logger = MyLogger # changing the logger
HTTPI.log_level = :info # changing the log level
Any help and feedback appreciated. So please get in touch!