Class: RestClient::Resource

Inherits:
Object
  • Object
show all
Defined in:
lib/restclient/resource.rb

Overview

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'

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Resource) initialize(url, options = {}, backwards_compatibility = nil, &block)

A new instance of Resource 



39
40
41
42
43
44
45
46
47
 
# File '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

Instance Attribute Details

- (Object) block (readonly)

Returns the value of attribute block 



37
38
39
 
# File 'lib/restclient/resource.rb', line 37

def block
  @block
end

- (Object) options (readonly)

Returns the value of attribute options 



37
38
39
 
# File 'lib/restclient/resource.rb', line 37

def options
  @options
end

- (Object) url (readonly)

Returns the value of attribute url 



37
38
39
 
# File 'lib/restclient/resource.rb', line 37

def url
  @url
end

Instance Method Details

- (Object) [](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'


150
151
152
153
154
155
156
157
 
# File '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

- (Object) concat_urls(url, suburl)

:nodoc: 



159
160
161
162
163
164
165
166
167
 
# File 'lib/restclient/resource.rb', line 159

def concat_urls(url, suburl) # :nodoc:
  url = url.to_s
  suburl = suburl.to_s
  if url.slice(-1, 1) == '/' or suburl.slice(0, 1) == '/'
    url + suburl
  else
    "#{url}/#{suburl}"
  end
end

- (Object) delete(additional_headers = {}, &block) 



92
93
94
95
96
97
98
 
# File '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

- (Object) get(additional_headers = {}, &block) 



49
50
51
52
53
54
55
 
# File '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

- (Object) head(additional_headers = {}, &block) 



57
58
59
60
61
62
63
 
# File '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

- (Object) headers 



112
113
114
 
# File 'lib/restclient/resource.rb', line 112

def headers
  options[:headers] || {}
end

- (Object) open_timeout 



120
121
122
 
# File 'lib/restclient/resource.rb', line 120

def open_timeout
  options[:open_timeout]
end

- (Object) password 



108
109
110
 
# File 'lib/restclient/resource.rb', line 108

def password
  options[:password]
end

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



83
84
85
86
87
88
89
90
 
# File '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

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



65
66
67
68
69
70
71
72
 
# File '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

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



74
75
76
77
78
79
80
81
 
# File '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

- (Object) timeout 



116
117
118
 
# File 'lib/restclient/resource.rb', line 116

def timeout
  options[:timeout]
end

- (Object) to_s 



100
101
102
 
# File 'lib/restclient/resource.rb', line 100

def to_s
  url
end

- (Object) user 



104
105
106
 
# File 'lib/restclient/resource.rb', line 104

def user
  options[:user]
end