File: README.rdoc

# README.rdoc

Path: | README.rdoc
Last Update: | Tue Aug 17 12:46:57 -0600 2010

# 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 'http://example.com/resource'
      RestClient.get 'https://user:password@example.com/private/resource'

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

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

See RestClient module docs for details.

## Usage: ActiveResource-Style

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

      private_resource = RestClient::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 RestClient::Resource module docs for details.

## Usage: Resource Nesting

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

See RestClient::Resource docs for details.

## Shell

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

      $ restclient
      >> RestClient.get 'http://example.com'

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

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

Add a user and password for authenticated resources:

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

Create ~/.restclient 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:

      $ restclient private_site

Use as a one-off, curl-style:

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

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

## Logging

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.

## Proxy

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

      RestClient.proxy = "http://proxy.example.com/"
      RestClient.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:

      RestClient.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 = RestClient.get 'http://example.com/action_which_sets_session_id'
      response.cookies
      # => {"_applicatioN_session_id" => "1234"}

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

## SSL Client Certificates

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

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: www.opensource.org/licenses/mit-license.php

rest-client.heroku.com

github.com/adamwiggins/rest-client

[Validate]