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:[email protected]/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_redis, #using_threads

Constructor Details

#initialize(uri_string, options = {}) ⇒ Uri

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

#default_headers ⇒ Object (readonly)

Returns the value of attribute default_headers.



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

def default_headers
  @default_headers
end

#password ⇒ Object (readonly)

Returns the value of attribute password.



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

def password
  @password
end

#query ⇒ Object (readonly)

Returns the value of attribute query.



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

def query
  @query
end

#uri ⇒ Object (readonly)

Returns the value of attribute uri.



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

def uri
  @uri
end

#uri_path ⇒ Object (readonly)

Returns the value of attribute uri_path.



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

def uri_path
  @uri_path
end

#uri_string ⇒ Object (readonly)

Returns the value of attribute uri_string.



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

def uri_string
  @uri_string
end

#username ⇒ Object (readonly)

Returns the value of attribute username.



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

def username
  @username
end

Instance Method Details

#==(other) ⇒ Object 



93
94
95
96
 
# File 'lib/wrest/uri.rb', line 93

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

#[](path, options = nil) ⇒ Object

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

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

:nodoc:



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

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

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

:nodoc:



110
111
112
 
# File 'lib/wrest/uri.rb', line 110

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

#build_patch(body = '', headers = {}, parameters = {}, &block) ⇒ Object

:nodoc:



120
121
122
 
# File 'lib/wrest/uri.rb', line 120

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

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

:nodoc:



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

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

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

:nodoc:



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

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

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

:nodoc:



115
116
117
 
# File 'lib/wrest/uri.rb', line 115

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

#clone(opts = {}) ⇒ Object

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
86
87
 
# File 'lib/wrest/uri.rb', line 83

def clone(opts = {})
  merged_options =  @options.merge(opts)
  merged_options[:default_headers] = opts[:default_headers] ? @default_headers.merge(opts[:default_headers]) : {}
  Uri.new(@uri_string, merged_options)
end

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

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



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

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

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

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.



255
256
257
 
# File 'lib/wrest/uri.rb', line 255

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

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


89
90
91
 
# File 'lib/wrest/uri.rb', line 89

def eql?(other)
  self == other
end

#full_path ⇒ Object

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



274
275
276
 
# File 'lib/wrest/uri.rb', line 274

def full_path
  uri.request_uri
end

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

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



145
146
147
 
# File 'lib/wrest/uri.rb', line 145

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

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

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.



156
157
158
 
# File 'lib/wrest/uri.rb', line 156

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

#hash ⇒ Object 



98
99
100
 
# File 'lib/wrest/uri.rb', line 98

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

#host ⇒ Object 



282
283
284
 
# File 'lib/wrest/uri.rb', line 282

def host
  uri.host
end

#https? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#options ⇒ Object

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.



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

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

#patch(body = '', headers = {}, parameters = {}, &block) ⇒ Object

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

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



183
184
185
 
# File 'lib/wrest/uri.rb', line 183

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

#patch_async(body = '', headers = {}, parameters = {}, &block) ⇒ Object

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

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

Note: patch_async does not return a response and the response should be accessed through callbacks.



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

def patch_async(body = '', headers = {}, parameters = {}, &block)
  @asynchronous_backend.execute(build_patch(body, headers, parameters, &block))
end

#port ⇒ Object 



286
287
288
 
# File 'lib/wrest/uri.rb', line 286

def port
  uri.port
end

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

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.

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



201
202
203
 
# File 'lib/wrest/uri.rb', line 201

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

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

Makes a POST request to this URI. This is a convenience API that creates a Wrest::Native::Post. 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.



211
212
213
 
# File 'lib/wrest/uri.rb', line 211

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

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

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



222
223
224
 
# File 'lib/wrest/uri.rb', line 222

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

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

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.



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

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

#protocol ⇒ Object 



278
279
280
 
# File 'lib/wrest/uri.rb', line 278

def protocol
  uri.scheme
end

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

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



164
165
166
 
# File 'lib/wrest/uri.rb', line 164

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

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

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.



175
176
177
 
# File 'lib/wrest/uri.rb', line 175

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

#to_s ⇒ Object

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.



105
106
107
 
# File 'lib/wrest/uri.rb', line 105

def to_s
  uri_string
end

#to_template(pattern) ⇒ Object

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