Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Interface for Ruby HTTP clients

Fetching latest commit…

Cannot retrieve the latest commit at this time


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


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

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

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

Notice: HTTPI does not force you to install any of these libraries. So please make sure to install the HTTP library of your choice and/or add it to your Gemfile. HTTPI will then load the library when executing HTTP requests. HTTPI will fall back to using net/http when any other adapter could not be loaded.


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_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!

Something went wrong with that request. Please try again.