HTTPI provides a common interface for Ruby HTTP libraries.

Wishlist | Bugs | Docs


The gem is available through Rubygems and can be installed via:

$ gem install httpi

Some examples

Executing a POST request with the most basic request object:

request = ""
HTTPI.get request

Here's a POST request with a request object:

request =
request.url = ""
request.body = "send me" request

And a GET request using HTTP basic auth and the Curb adapter:

request =
request.url = ""
request.auth.basic "username", "password"

HTTPI.get request, :curb

HTTPI also comes shortcuts. This executes a PUT request:

HTTPI.put "", "<some>xml</some>"

And this executes a DELETE request:

HTTPI.delete ""


The HTTPI module uses one of the available adapters to execute HTTP requests.


HTTPI.get(request, adapter = nil)
HTTPI.get(url, adapter = nil)

POST, adapter = nil), 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

More control

If you need more control over the request, you can access the HTTP client instance represented by your adapter in a block: request do |http|
  http.use_ssl = true  # Curb example


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)

Usage example

request =
request.url = ""
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

Usage example

request =
request.auth.basic "username", "password"


  • Add support for NTLM authentication


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]

Usage example

request =
request.auth.ssl.cert_key_file = "client_key.pem"
request.auth.ssl.cert_file = "client_cert.pem"
request.auth.ssl.verify_mode = :none


HTTPI uses adapters to support multiple HTTP libraries. It currently contains adapters for:

By default, HTTPI uses the HTTPClient. But changing the default is fairly easy:

HTTPI::Adapter.use = :curb  # or one of [:httpclient, :net_http]


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 ...>"


  • Return the original HTTPI::Request for debugging purposes
  • Return the time it took to execute the request


Any help and feedback appreciated. So please get in touch!