module RestClient

This module's static methods are the entry point for using the REST client.

# GET
xml = RestClient.get 'http://example.com/resource'
jpg = RestClient.get 'http://example.com/resource', :accept => 'image/jpg'

# authentication and SSL
RestClient.get 'https://user:password@example.com/private/resource'

# POST or PUT with a hash sends parameters as a urlencoded form body
RestClient.post 'http://example.com/resource', :param1 => 'one'

# nest hash parameters
RestClient.post 'http://example.com/resource', :nested => { :param1 => 'one' }

# POST and PUT with raw payloads
RestClient.post 'http://example.com/resource', 'the post body', :content_type => 'text/plain'
RestClient.post 'http://example.com/resource.xml', xml_doc
RestClient.put 'http://example.com/resource.pdf', File.read('my.pdf'), :content_type => 'application/pdf'

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

# retreive the response http code and headers
res = RestClient.get 'http://example.com/some.jpg'
res.code                    # => 200
res.headers[:content_type]  # => 'image/jpg'

# HEAD
RestClient.head('http://example.com').headers

To use with a proxy, just set RestClient.proxy to the proper http proxy:

RestClient.proxy = "http://proxy.example.com/"

Or inherit the proxy from the environment:

RestClient.proxy = ENV['http_proxy']

For live tests of RestClient, try using rest-test.heroku.com, which echoes back information about the rest call:

>> RestClient.put 'http://rest-test.heroku.com/resource', :foo => 'baz'
=> "PUT http://rest-test.heroku.com/resource with a 7 byte payload, content type application/x-www-form-urlencoded {\"foo\"=>\"baz\"}"

Constants

STATUSES

Hash of HTTP status code => message.

1xx: Informational - Request received, continuing process 2xx: Success - The action was successfully received, understood, and

accepted

3xx: Redirection - Further action must be taken in order to complete the

request

4xx: Client Error - The request contains bad syntax or cannot be fulfilled 5xx: Server Error - The server failed to fulfill an apparently valid

request

@see

http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
STATUSES_COMPATIBILITY
VERSION
VERSION_INFO

Public Class Methods

add_before_execution_proc(&proc) click to toggle source

Add a Proc to be called before each request in executed. The proc parameters will be the http request and the request params.

# File lib/restclient.rb, line 169
def self.add_before_execution_proc &proc
  raise ArgumentError.new('block is required') unless proc
  @@before_execution_procs << proc
end
create_log(param) click to toggle source

Create a log that respond to << like a logger param can be 'stdout', 'stderr', a string (then we will log to that file) or a logger (then we return it)

# File lib/restclient.rb, line 122
def self.create_log param
  if param
    if param.is_a? String
      if param == 'stdout'
        stdout_logger = Class.new do
          def << obj
            STDOUT.puts obj
          end
        end
        stdout_logger.new
      elsif param == 'stderr'
        stderr_logger = Class.new do
          def << obj
            STDERR.puts obj
          end
        end
        stderr_logger.new
      else
        file_logger = Class.new do
          attr_writer :target_file

          def << obj
            File.open(@target_file, 'a') { |f| f.puts obj }
          end
        end
        logger = file_logger.new
        logger.target_file = param
        logger
      end
    else
      param
    end
  end
end
delete(url, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 81
def self.delete(url, headers={}, &block)
  Request.execute(:method => :delete, :url => url, :headers => headers, &block)
end
get(url, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 65
def self.get(url, headers={}, &block)
  Request.execute(:method => :get, :url => url, :headers => headers, &block)
end
head(url, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 85
def self.head(url, headers={}, &block)
  Request.execute(:method => :head, :url => url, :headers => headers, &block)
end
log=(log) click to toggle source

Setup the log for RestClient calls. Value should be a logger but can can be stdout, stderr, or a filename. You can also configure logging by the environment variable RESTCLIENT_LOG.

# File lib/restclient.rb, line 116
def self.log= log
  @@log = create_log log
end
options(url, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 89
def self.options(url, headers={}, &block)
  Request.execute(:method => :options, :url => url, :headers => headers, &block)
end
patch(url, payload, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 73
def self.patch(url, payload, headers={}, &block)
  Request.execute(:method => :patch, :url => url, :payload => payload, :headers => headers, &block)
end
post(url, payload, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 69
def self.post(url, payload, headers={}, &block)
  Request.execute(:method => :post, :url => url, :payload => payload, :headers => headers, &block)
end
proxy() click to toggle source

A global proxy URL to use for all requests. This can be overridden on a per-request basis by passing `:proxy` to RestClient::Request.

# File lib/restclient.rb, line 95
def self.proxy
  @proxy ||= nil
end
proxy=(value) click to toggle source
# File lib/restclient.rb, line 99
def self.proxy=(value)
  @proxy = value
  @proxy_set = true
end
proxy_set?() click to toggle source

Return whether RestClient.proxy was set explicitly. We use this to differentiate between no value being set and a value explicitly set to nil.

@return [Boolean]

# File lib/restclient.rb, line 109
def self.proxy_set?
  @proxy_set ||= false
end
put(url, payload, headers={}, &block) click to toggle source
# File lib/restclient.rb, line 77
def self.put(url, payload, headers={}, &block)
  Request.execute(:method => :put, :url => url, :payload => payload, :headers => headers, &block)
end
reset_before_execution_procs() click to toggle source

Reset the procs to be called before each request is executed.

# File lib/restclient.rb, line 175
def self.reset_before_execution_procs
  @@before_execution_procs = []
end
version() click to toggle source
# File lib/restclient/version.rb, line 5
def self.version
  VERSION
end

Public Instance Methods

<<(obj) click to toggle source
# File lib/restclient.rb, line 127
def << obj
  STDOUT.puts obj
end