Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
157 lines (98 sloc) 4.5 KB

This fork is no longer maintained. Please see the new official fork at:

REST Client – simple DSL for accessing REST resources

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

Usage: Raw URL

require 'rest_client'

RestClient.get ''
RestClient.get '' '', :param1 => 'one', :nested => { :param2 => 'two' }

RestClient.delete ''

See RestClient module docs for details.

Usage: ActiveResource-Style

resource = ''

private_resource = '', :user => 'adam', :password => 'secret', :timeout => 20, :open_timeout => 5
private_resource.put'pic.jpg'), :content_type => 'image/jpg'

See RestClient::Resource module docs for details.

Usage: Resource Nesting

site ='')
site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'

See RestClient::Resource docs for details.


The restclient shell command gives an IRB session with RestClient already loaded:

$ restclient
>> RestClient.get ''

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

$ restclient
>> put '/resource', 'data'

Add a user and password for authenticated resources:

$ restclient user pass
>> delete '/private/resource'

Create ~/.restclient for named sessions:

  url: http://localhost:4567
  url: http://localhost:9292
  username: user
  password: pass

Then invoke:

$ restclient private_site

Use as a one-off, curl-style:

$ restclient get > output_body

$ restclient put < input_body


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

RestClient.log = '/tmp/restclient.log'

Or set an environment variable to avoid modifying the code:

$ RESTCLIENT_LOG=stdout path/to/my/program

Either produces logs like this:

RestClient.get "http://some/resource"
# => 200 OK | text/html 250 bytes
RestClient.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 restclient shell or a script to replay your sequence of rest calls.


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

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

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:

RestClient.proxy = ENV['http_proxy']


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

response = RestClient.get ''
# => {"_applicatioN_session_id" => "1234"}

response2 =
  {:param1 => "foo"},
  {:cookies => {:session_id => "1234"}}
# ...response body

SSL Client Certificates
  :ssl_client_cert  =>"cert.pem")), 
  :ssl_client_key   =>"key.pem"), "passphrase, if any"),
  :ssl_ca_file      =>  "ca_certificate.pem", 
  :verify_ssl       =>  OpenSSL::SSL::VERIFY_PEER 

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


Written by Adam Wiggins (adam at heroku dot com)

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, Paul Dlug, and Brad Ediger

Released under the MIT License: