Class: Wrest::Uri

Inherits:
Object
  • Object
show all
Includes:
Http::ConnectionFactory, Multipart, Builders
Defined in:
lib/wrest/uri.rb,
lib/wrest/multipart.rb,
lib/wrest/uri/builders.rb

Overview

Wrest::Uri provides a simple api for REST calls. String#to_uri is a convenience method to build a Wrest::Uri from a string url. Note that a Wrest::Uri is immutable.

Basic HTTP Authentication is supported. Example:

"http://kaiwren:fupuppies@coathangers.com/portal/1".to_uri
"http://coathangers.com/portal/1".to_uri(:username => 'kaiwren', :password => 'fupuppies')

The second form is preferred as it can handle passwords with special characters like ^ and @

You can find examples that use real APIs (like delicious) under the wrest/examples directory.

Defined Under Namespace

Modules: Builders

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from Multipart

#post_multipart, #post_multipart_async, #put_multipart, #put_multipart_async

Methods included from Builders

#disable_cache, #using_cookie, #using_em, #using_hash, #using_memcached, #using_threads

Constructor Details

- (Uri) initialize(uri_string, options = {})

Valid tuples for the options are:

:asynchronous_backend => Can currently be set to either Wrest::AsyncRequest::EventMachineBackend.new
                         or Wrest::AsyncRequest::ThreadBackend.new. Easier to do using Uri#using_em and
                         Uri#using_threads.
:callback             => Accepts a hash where the keys are response codes or ranges of response codes and
                         the values are the corresponding blocks that will be invoked should the response
                         code match the key.
:default_headers      => Accepts a hash containing a set of default request headers with which the headers
                         passed to Uri#get, Uri#post etc. are merged. Incoming headers will override the
                         defaults if there are any clashes. Use this to set cookies or use OAuth2 Authorize
                         headers. When extending or cloning a Uri, passing in a new set of default_headers
                         will result in the old set being overridden.

See Wrest::Native::Request for other available options and their default values.



40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/wrest/uri.rb', line 40

def initialize(uri_string, options = {})
  @options = options.clone
  @uri_string = uri_string.to_s
  @uri = URI.parse(@uri_string)
  uri_scheme = URI.split(@uri_string)
  @uri_path = uri_scheme[-4].split('?').first || ''
  @uri_path = (@uri_path.empty? ? '/' : @uri_path) 
  @query = uri_scheme[-2] || ''
  @username = (@options[:username] ||= @uri.user)
  @password = (@options[:password] ||= @uri.password)
  @asynchronous_backend = @options[:asynchronous_backend] || Wrest::AsyncRequest.default_backend
  @options[:callback] = Callback.new(@options[:callback]) if @options[:callback]
  @default_headers = @options[:default_headers] || {}
end

Instance Attribute Details

- (Object) default_headers (readonly)

Returns the value of attribute default_headers



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def default_headers
  @default_headers
end

- (Object) password (readonly)

Returns the value of attribute password



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def password
  @password
end

- (Object) query (readonly)

Returns the value of attribute query



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def query
  @query
end

- (Object) uri (readonly)

Returns the value of attribute uri



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def uri
  @uri
end

- (Object) uri_path (readonly)

Returns the value of attribute uri_path



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def uri_path
  @uri_path
end

- (Object) uri_string (readonly)

Returns the value of attribute uri_string



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def uri_string
  @uri_string
end

- (Object) username (readonly)

Returns the value of attribute username



25
26
27
 
# File 'lib/wrest/uri.rb', line 25

def username
  @username
end

Instance Method Details

- (Object) ==(other) 



91
92
93
94
 
# File 'lib/wrest/uri.rb', line 91

def ==(other)
  return false if other.class != self.class
  return other.uri == self.uri && self.username == other.username && self.password == other.password
end

- (Object) [](path, options = nil)

Build a new Wrest::Uri by appending path to the current uri. If the original Wrest::Uri has a username and password, that will be copied to the new Wrest::Uri as well.

Example:

uri = "https://localhost:3000/v1".to_uri
uri['/oogas/1'].get

To change the username and password on the new instance, simply pass them as an options map.

Example:

uri = "https://localhost:3000/v1".to_uri(:username => 'foo', :password => 'bar')
uri['/oogas/1', {:username => 'meh', :password => 'baz'}].get


77
78
79
 
# File 'lib/wrest/uri.rb', line 77

def [](path, options = nil)
  Uri.new(uri + File.join(uri_path, path), options || @options)
end

- (Object) build_delete(parameters = {}, headers = {}, &block)

:nodoc:



130
131
132
 
# File 'lib/wrest/uri.rb', line 130

def build_delete(parameters = {}, headers = {}, &block)
  Http::Delete.new(self, parameters, default_headers.merge(headers), block ? @options.merge(:callback_block => block) : @options)
end

- (Object) build_get(parameters = {}, headers = {}, &block)

:nodoc:



108
109
110
 
# File 'lib/wrest/uri.rb', line 108

def build_get(parameters = {}, headers = {}, &block)
  Http::Get.new(self, parameters, default_headers.merge(headers), block ? @options.merge(:callback_block => block) : @options)
end

- (Object) build_post(body = '', headers = {}, parameters = {}, &block)

:nodoc:



118
119
120
 
# File 'lib/wrest/uri.rb', line 118

def build_post(body = '', headers = {}, parameters = {}, &block)
  Http::Post.new(self, body.to_s, default_headers.merge(headers), parameters, block ? @options.merge(:callback_block => block) : @options)
end

- (Object) build_post_form(parameters = {}, headers = {}, &block)

:nodoc:



123
124
125
126
127
 
# File 'lib/wrest/uri.rb', line 123

def build_post_form(parameters ={}, headers = {}, &block)
  headers = default_headers.merge(headers).merge(Wrest::H::ContentType => Wrest::T::FormEncoded)
  body = parameters.to_query
  Http::Post.new(self, body, headers, {}, block ? @options.merge(:callback_block => block) : @options)
end

- (Object) build_put(body = '', headers = {}, parameters = {}, &block)

:nodoc:



113
114
115
 
# File 'lib/wrest/uri.rb', line 113

def build_put(body = '', headers = {}, parameters = {}, &block)
  Http::Put.new(self, body.to_s, default_headers.merge(headers), parameters, block ? @options.merge(:callback_block => block) : @options)
end

- (Object) clone(opts = {})

Clones a Uri, building a new instance with exactly the same uri string. You can however change the Uri options or add new ones.



83
84
85
 
# File 'lib/wrest/uri.rb', line 83

def clone(opts = {})
  Uri.new(@uri_string, @options.merge(opts))
end

- (Object) delete(parameters = {}, headers = {}, &block)

Makes a DELETE request to this URI. This is a convenience API that creates a Wrest::Native::Delete, executes it and returns a Wrest::Native::Response.

Remember to escape all parameter strings if necessary, using URI.escape



226
227
228
 
# File 'lib/wrest/uri.rb', line 226

def delete(parameters = {}, headers = {}, &block)
  build_delete(parameters, headers, &block).invoke
end

- (Object) delete_async(parameters = {}, headers = {}, &block)

Makes a DELETE request to this URI. This is a convenience API that creates a Wrest::Native::Delete.

Remember to escape all parameter strings if necessary, using URI.escape

Note: delete_async does not return a response and the response should be accessed through callbacks. This implementation of asynchronous delete is currently in alpha. Hence, it should not be used in production.



237
238
239
240
 
# File 'lib/wrest/uri.rb', line 237

def delete_async(parameters = {}, headers = {}, &block)
  @asynchronous_backend.execute(build_delete(parameters, headers, &block))
  nil
end

- (Boolean) eql?(other)

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/wrest/uri.rb', line 87

def eql?(other)
  self == other
end

- (Object) full_path

Provides the full path of a request. For example, for

http://localhost:3000/demons/1/chi?sort=true

this would return

/demons/1/chi?sort=true


257
258
259
 
# File 'lib/wrest/uri.rb', line 257

def full_path
  uri.request_uri
end

- (Object) get(parameters = {}, headers = {}, &block)

Make a GET request to this URI. This is a convenience API that creates a Wrest::Native::Get, executes it and returns a Wrest::Native::Response.

Remember to escape all parameter strings if necessary, using URI.escape



138
139
140
 
# File 'lib/wrest/uri.rb', line 138

def get(parameters = {}, headers = {}, &block)
  build_get(parameters, headers, &block).invoke
end

- (Object) get_async(parameters = {}, headers = {}, &block)

Make a GET request to this URI. This is a convenience API that creates a Wrest::Native::Get.

Remember to escape all parameter strings if necessary, using URI.escape

Note: get_async does not return a response and the response should be accessed through callbacks. This implementation of asynchronous get is currently in alpha. Hence, it should not be used in production.



149
150
151
152
 
# File 'lib/wrest/uri.rb', line 149

def get_async(parameters = {}, headers = {}, &block)
  @asynchronous_backend.execute(build_get(parameters, headers, &block))
  nil
end

- (Object) hash 



96
97
98
 
# File 'lib/wrest/uri.rb', line 96

def hash
  @uri.hash + @username.hash + @password.hash + 20090423
end

- (Object) host 



265
266
267
 
# File 'lib/wrest/uri.rb', line 265

def host
  uri.host
end

- (Boolean) https?

Returns:

  • (Boolean) 


248
249
250
 
# File 'lib/wrest/uri.rb', line 248

def https? 
  @uri.is_a?(URI::HTTPS)
end

- (Object) options

Makes an OPTIONS request to this URI. This is a convenience API that creates a Wrest::Native::Options, executes it and returns the Wrest::Native::Response.



244
245
246
 
# File 'lib/wrest/uri.rb', line 244

def options
  Http::Options.new(self, @options).invoke
end

- (Object) port 



269
270
271
 
# File 'lib/wrest/uri.rb', line 269

def port
  uri.port
end

- (Object) post(body = '', headers = {}, parameters = {}, &block)

Makes a POST request to this URI. This is a convenience API that creates a Wrest::Native::Post, executes it and returns a Wrest::Native::Response. Note that sending an empty body will blow up if you're using libcurl.

Remember to escape all parameter strings if necessary, using URI.escape



179
180
181
 
# File 'lib/wrest/uri.rb', line 179

def post(body = '', headers = {}, parameters = {}, &block)
  build_post(body, headers, parameters, &block).invoke
end

- (Object) post_async(body = '', headers = {}, parameters = {}, &block)

Makes a POST request to this URI. This is a convenience API that creates a Wrest::Native::Post. Note that sending an empty body will blow up if you're using libcurl.

Remember to escape all parameter strings if necessary, using URI.escape

Note: post_async does not return a response and the response should be accessed through callbacks. This implementation of asynchronous post is currently in alpha. Hence, it should not be used in production.



191
192
193
194
 
# File 'lib/wrest/uri.rb', line 191

def post_async(body = '', headers = {}, parameters = {}, &block)
  @asynchronous_backend.execute(build_post(body, headers, parameters, &block))
  nil
end

- (Object) post_form(parameters = {}, headers = {}, &block)

Makes a POST request to this URI. This is a convenience API that mimics a form being posted; some allegly RESTful APIs like FCBK require this.

Form encoding involves munging the parameters into a string and placing them in the body, as well as setting the Content-Type header to application/x-www-form-urlencoded



203
204
205
 
# File 'lib/wrest/uri.rb', line 203

def post_form(parameters = {}, headers = {}, &block)
  build_post_form(parameters, headers, &block).invoke
end

- (Object) post_form_async(parameters = {}, headers = {}, &block)

Makes a POST request to this URI. This is a convenience API that mimics a form being posted; some allegly RESTful APIs like FCBK require this.

Form encoding involves munging the parameters into a string and placing them in the body, as well as setting the Content-Type header to application/x-www-form-urlencoded

Note: post_form_async does not return a response and the response should be accessed through callbacks. This implementation of asynchronous post_form is currently in alpha. Hence, it should not be used in production.



217
218
219
220
 
# File 'lib/wrest/uri.rb', line 217

def post_form_async(parameters = {}, headers = {}, &block)
  @asynchronous_backend.execute(build_post_form(parameters, headers, &block))
  nil
end

- (Object) protocol 



261
262
263
 
# File 'lib/wrest/uri.rb', line 261

def protocol
  uri.scheme
end

- (Object) put(body = '', headers = {}, parameters = {}, &block)

Make a PUT request to this URI. This is a convenience API that creates a Wrest::Native::Put, executes it and returns a Wrest::Native::Response.

Remember to escape all parameter strings if necessary, using URI.escape



158
159
160
 
# File 'lib/wrest/uri.rb', line 158

def put(body = '', headers = {}, parameters = {}, &block)
  build_put(body, headers, parameters, &block).invoke
end

- (Object) put_async(body = '', headers = {}, parameters = {}, &block)

Make a PUT request to this URI. This is a convenience API that creates a Wrest::Native::Put.

Remember to escape all parameter strings if necessary, using URI.escape

Note: put_async does not return a response and the response should be accessed through callbacks. This implementation of asynchronous put is currently in alpha. Hence, it should not be used in production.



169
170
171
172
 
# File 'lib/wrest/uri.rb', line 169

def put_async(body = '', headers = {}, parameters = {}, &block)
  @asynchronous_backend.execute(build_put(body, headers, parameters, &block))
  nil
end

- (Object) to_s

This produces exactly the same string as the Wrest::Uri was constructed with. If the orignial URI contained a HTTP username and password, that too will show up, so be careful if using this for logging.



103
104
105
 
# File 'lib/wrest/uri.rb', line 103

def to_s
  uri_string
end

- (Object) to_template(pattern)

Builds a Wrest::UriTemplate by extending the current URI with the pattern passed to it.



57
58
59
60
 
# File 'lib/wrest/uri.rb', line 57

def to_template(pattern)
  template_pattern = URI.join(uri_string,pattern).to_s
  UriTemplate.new(template_pattern, @options)
end