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:password@example.com/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.

Meta

This library began its life as RestClient. Due to some changes and the desire to not conflict with the original library, Sevenwire forked and renamed it.

RestClient was written by Adam Wiggins (adam at heroku dot com)

RestClient Patches contributed by: Chris Anderson, Greg Borenstein, Ardekantur, Pedro Belo, Rafael Souza, Rick Olson, Aman Gupta, Blake Mizerany, Brian Donovan, Ivan Makfinsky, Marc-André Cournoyer, Coda Hale, Tetsuo Watanabe, Dusty Doris, Lennon Day-Reynolds, James Edward Gray II, Cyril Rohr, Juan Alvarez, and Adam Jacob

Released under the MIT License: www.opensource.org/licenses/mit-license.php

RestClient can be found at:

rest-client.heroku.com

github.com/adamwiggins/rest-client

HttpClient can be found at:

github.com/sevenwire/http-client