HTTP Client – simple DSL for accessing HTTP resources

A simple HTTP client for Ruby, inspired by the Sinatra’s microframework style of specifying actions: get, put, post, delete.

Usage: Raw URL

require 'http_client'

HttpClient.get 'http://example.com/resource'
HttpClient.get 'https://user:[email protected]/private/resource'

HttpClient.post 'http://example.com/resource', :param1 => 'one', :nested => { :param2 => 'two' }

HttpClient.delete 'http://example.com/resource'

See HttpClient module docs for details.

Usage: ActiveResource-Style

resource = HttpClient::Resource.new 'http://example.com/resource'
resource.get

private_resource = HttpClient::Resource.new 'https://example.com/private/resource', :user => 'adam', :password => 'secret', :timeout => 20, :open_timeout => 5
private_resource.put File.read('pic.jpg'), :content_type => 'image/jpg'

See HttpClient::Resource module docs for details.

Usage: Resource Nesting

site = HttpClient::Resource.new('http://example.com')
site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'

See HttpClient::Resource docs for details.

Shell

The http_client shell command gives an IRB session with HttpClient already loaded:

$ http_client
>> HttpClient.get 'http://example.com'

Specify a URL argument for get/post/put/delete on that resource:

$ http_client http://example.com
>> put '/resource', 'data'

Add a user and password for authenticated resources:

$ http_client https://example.com user pass
>> delete '/private/resource'

Create ~/.http_client for named sessions:

sinatra:
  url: http://localhost:4567
rack:
  url: http://localhost:9292
private_site:
  url: http://example.com
  username: user
  password: pass

Then invoke:

$ http_client private_site

Use as a one-off, curl-style:

$ http_client get http://example.com/resource > output_body

$ http_client put http://example.com/resource < input_body

Logging

Write calls to a log filename (can also be “stdout” or “stderr”):

HttpClient.log = '/tmp/http_client.log'

Or set an environment variable to avoid modifying the code:

$ HTTPCLIENT_LOG=stdout path/to/my/program

Either produces logs like this:

HttpClient.get "http://some/resource"
# => 200 OK | text/html 250 bytes
HttpClient.put "http://some/resource", "payload"
# => 401 Unauthorized | application/xml 340 bytes

Note that these logs are valid Ruby, so you can paste them into the http_client shell or a script to replay your sequence of http calls.

Proxy

All calls to HttpClient, including Resources, will use the proxy specified by HttpClient.proxy:

HttpClient.proxy = "http://proxy.example.com/"
HttpClient.get "http://some/resource"
# => response from some/resource as proxied through proxy.example.com

Often the proxy url is set in an environment variable, so you can do this to use whatever proxy the system is configured to use:

HttpClient.proxy = ENV['http_proxy']

Cookies

Request and Response objects know about HTTP cookies, and will automatically extract and set headers for them as needed:

response = HttpClient.get 'http://example.com/action_which_sets_session_id'
response.cookies
# => {"_applicatioN_session_id" => "1234"}

response2 = HttpClient.post(
  'http://localhost:3000/',
  {:param1 => "foo"},
  {:cookies => {:session_id => "1234"}}
)
# ...response body

SSL Client Certificates

HttpClient::Resource.new(
  'https://example.com', 
  :ssl_client_cert  =>  OpenSSL::X509::Certificate.new(File.read("cert.pem")), 
  :ssl_client_key   =>  OpenSSL::PKey::RSA.new(File.read("key.pem"), "passphrase, if any"),
  :ssl_ca_file      =>  "ca_certificate.pem", 
  :verify_ssl       =>  OpenSSL::SSL::VERIFY_PEER 
).get

Self-signed certificates can be generated with the openssl command-line tool.