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)



39
40
41
42
43
44
45
46
# File 'lib/restclient/resource.rb', line 39

def initialize(url, options={}, backwards_compatibility=nil)
	@url = url
	if options.class == Hash
		@options = options
	else # compatibility with previous versions
		@options = { :user => options, :password => backwards_compatibility }
	end
end

Instance Attribute Details

- (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)

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'


132
133
134
# File 'lib/restclient/resource.rb', line 132

def [](suburl)
	self.class.new(concat_urls(url, suburl), options)
end

- (Object) concat_urls(url, suburl)

:nodoc:



136
137
138
139
140
141
142
143
144
# File 'lib/restclient/resource.rb', line 136

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 = {})



74
75
76
77
78
79
80
# File 'lib/restclient/resource.rb', line 74

def delete(additional_headers={})
	Request.execute(options.merge(
		:method => :delete,
		:url => url,
		:headers => headers.merge(additional_headers)
	))
end

- (Object) get(additional_headers = {})



48
49
50
51
52
53
54
# File 'lib/restclient/resource.rb', line 48

def get(additional_headers={})
	Request.execute(options.merge(
		:method => :get,
		:url => url,
		:headers => headers.merge(additional_headers)
	))
end

- (Object) headers



94
95
96
# File 'lib/restclient/resource.rb', line 94

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

- (Object) open_timeout



102
103
104
# File 'lib/restclient/resource.rb', line 102

def open_timeout
	options[:open_timeout]
end

- (Object) password



90
91
92
# File 'lib/restclient/resource.rb', line 90

def password
	options[:password]
end

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



56
57
58
59
60
61
62
63
# File 'lib/restclient/resource.rb', line 56

def post(payload, additional_headers={})
	Request.execute(options.merge(
		:method => :post,
		:url => url,
		:payload => payload,
		:headers => headers.merge(additional_headers)
	))
end

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



65
66
67
68
69
70
71
72
# File 'lib/restclient/resource.rb', line 65

def put(payload, additional_headers={})
	Request.execute(options.merge(
		:method => :put,
		:url => url,
		:payload => payload,
		:headers => headers.merge(additional_headers)
	))
end

- (Object) timeout



98
99
100
# File 'lib/restclient/resource.rb', line 98

def timeout
	options[:timeout]
end

- (Object) to_s



82
83
84
# File 'lib/restclient/resource.rb', line 82

def to_s
	url
end

- (Object) user



86
87
88
# File 'lib/restclient/resource.rb', line 86

def user
	options[:user]
end