Class: RestClient::Resource

A class that can be instantiated for access to a RESTful resource, including authentication.

Example:

  resource = RestClient::Resource.new('http://some/resource')
  jpg = resource.get(:accept => 'image/jpg')

With HTTP basic authentication:

  resource = RestClient::Resource.new('http://protected/resource', :user => 'user', :password => 'password')
  resource.delete

With a timeout (seconds):

  RestClient::Resource.new('http://slow', :timeout => 10)

With an open timeout (seconds):

  RestClient::Resource.new('http://behindfirewall', :open_timeout => 10)

You can also use resources to share common headers. For headers keys, symbols are converted to strings. Example:

  resource = RestClient::Resource.new('http://some/resource', :headers => { :client_version => 1 })

This header will be transported as X-Client-Version (notice the X prefix, capitalization and hyphens)

Use the [] syntax to allocate subresources:

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

Methods

[] delete get head headers new open_timeout password patch post put timeout to_s user

Attributes

 block
 options
 url

Public Class methods

new(url, options={}, backwards_compatibility=nil, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 39
    def initialize(url, options={}, backwards_compatibility=nil, &block)
      @url = url
      @block = block
      if options.class == Hash
        @options = options
      else # compatibility with previous versions
        @options = { :user => options, :password => backwards_compatibility }
      end
    end

Public Instance methods

[](suburl, &new_block)

Construct a subresource, preserving authentication.

Example:

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

This is especially useful if you wish to define your site in one place and call it in multiple locations:

  def orders
    RestClient::Resource.new('http://example.com/orders', 'admin', 'mypasswd')
  end

  orders.get                     # GET http://example.com/orders
  orders['1'].get                # GET http://example.com/orders/1
  orders['1/items'].delete       # DELETE http://example.com/orders/1/items

Nest resources as far as you want:

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

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 150
    def [](suburl, &new_block)
      case
        when block_given? then self.class.new(concat_urls(url, suburl), options, &new_block)
        when block        then self.class.new(concat_urls(url, suburl), options, &block)
      else
        self.class.new(concat_urls(url, suburl), options)
      end
    end

delete(additional_headers={}, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 92
    def delete(additional_headers={}, &block)
      headers = (options[:headers] || {}).merge(additional_headers)
      Request.execute(options.merge(
              :method => :delete,
              :url => url,
              :headers => headers), &(block || @block))
    end

get(additional_headers={}, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 49
    def get(additional_headers={}, &block)
      headers = (options[:headers] || {}).merge(additional_headers)
      Request.execute(options.merge(
              :method => :get,
              :url => url,
              :headers => headers), &(block || @block))
    end

head(additional_headers={}, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 57
    def head(additional_headers={}, &block)
      headers = (options[:headers] || {}).merge(additional_headers)
      Request.execute(options.merge(
              :method => :head,
              :url => url,
              :headers => headers), &(block || @block))
    end

headers()

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 112
    def headers
      options[:headers] || {}
    end

open_timeout()

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 120
    def open_timeout
      options[:open_timeout]
    end

password()

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 108
    def password
      options[:password]
    end

patch(payload, additional_headers={}, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 83
    def patch(payload, additional_headers={}, &block)
      headers = (options[:headers] || {}).merge(additional_headers)
      Request.execute(options.merge(
              :method => :patch,
              :url => url,
              :payload => payload,
              :headers => headers), &(block || @block))
    end

post(payload, additional_headers={}, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 65
    def post(payload, additional_headers={}, &block)
      headers = (options[:headers] || {}).merge(additional_headers)
      Request.execute(options.merge(
              :method => :post,
              :url => url,
              :payload => payload,
              :headers => headers), &(block || @block))
    end

put(payload, additional_headers={}, &block)

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 74
    def put(payload, additional_headers={}, &block)
      headers = (options[:headers] || {}).merge(additional_headers)
      Request.execute(options.merge(
              :method => :put,
              :url => url,
              :payload => payload,
              :headers => headers), &(block || @block))
    end

timeout()

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 116
    def timeout
      options[:timeout]
    end

to_s()

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 100
    def to_s
      url
    end

user()

[Source]

# File lib/rest-client-1.6.3/lib/restclient/resource.rb, line 104
    def user
      options[:user]
    end