HTTPI
HTTPI provides a common interface for Ruby HTTP libraries.
Installation
HTTPI is available through Rubygems and can be installed via:
$ gem install httpi
Getting started
In order to provide a common interface, HTTPI provides the HTTPI::Request
object for you to
configure your request. Here's a very simple GET request.
request = HTTPI::Request.new("http://example.com")
HTTPI.get request
To execute a POST request, you may want to specify a payload.
request = HTTPI::Request.new
request.url = "http://post.example.com"
request.body = "some data"
HTTPI.post request
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:
- httpclient ~> 2.1.5
- curb ~> 0.7.8
- net/http
You can manually specify the adapter to use via:
HTTPI.adapter = :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.
HTTPI::Request
URL
request.url = "http://example.com"
request.url # => #<URI::HTTP:0x101c1ab18 URL:http://example.com>
Proxy
request.proxy = "http://example.com"
request.proxy # => #<URI::HTTP:0x101c1ab18 URL:http://example.com>
Headers
request.headers["Accept-Charset"] = "utf-8"
request.headers = { "Accept-Charset" => "utf-8" }
request.headers # => { "Accept-Charset" => "utf-8" }
Body
request.body = "some data"
request.body # => "some data"
Open timeout
request.open_timeout = 30 # sec
Read timeout
request.read_timeout = 30 # sec
HTTPI::Auth
HTTPI::Auth
supports HTTP basic and digest authentication.
request.auth.basic("username", "password") # HTTP basic auth credentials
request.auth.digest("username", "password") # HTTP digest auth credentials
request.auth.ntlm("username", "password") # NTLM auth credentials
HTTPI::Auth::SSL
HTTPI::Auth::SSL
manages SSL client authentication.
request.auth.ssl.cert_key_file = "client_key.pem" # the private key file to use
request.auth.ssl.cert_key_password = "C3rtP@ssw0rd" # the key file's password
request.auth.ssl.cert_file = "client_cert.pem" # the certificate file to use
request.auth.ssl.ca_cert_file = "ca_cert.pem" # the ca certificate file to use
request.auth.ssl.verify_mode = :none # or one of [:peer, :fail_if_no_peer_cert, :client_once]
HTTPI::Response
Every request returns 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
Logging
HTTPI by default logs each HTTP request to STDOUT using a log level of :debug.
HTTPI.log = false # disable logging
HTTPI.logger = MyLogger # change the logger
HTTPI.log_level = :info # change the log level