Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Interface for Ruby HTTP clients

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 autotest
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .autotest
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .rspec
Octocat-spinner-32 Gemfile
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 httpi.gemspec
README.md

HTTPI

HTTPI provides a common interface for Ruby HTTP libraries.

Wishlist | Bugs | Docs

Installation

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

HTTPI

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

GET

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

POST

HTTPI.post(request, adapter = nil)
HTTPI.post(url, body, adapter = nil)

HEAD

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

PUT

HTTPI.put(request, adapter = nil)
HTTPI.put(url, body, adapter = nil)

DELETE

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

Notice

  • 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:

HTTPI.post request do |http|
  http.use_ssl = true  # Curb example
end

HTTPI::Adapter

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. Instead you need to 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::Request

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 = HTTPI::Request.new
request.url = "http://example.com"
request.read_timeout = 30

HTTPI::Auth

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 = HTTPI::Request.new
request.auth.basic "username", "password"

TODO

  • Add support for NTLM authentication

HTTPI::Auth::SSL

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 = 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

HTTPI::Response

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.

TODO

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

Participate

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

Something went wrong with that request. Please try again.