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.
:username, :password  => HTTP authentication. Passing nil for either username or password will skip it.

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



43
44
45
46
47
 
# File 'lib/wrest/uri.rb', line 43

def initialize(uri_string, options = {})
  @options = options.clone
  setup_uri_state!(uri_string)
  setup_request_config!
end

Instance Attribute Details

#default_headers ⇒ Object (readonly)

Returns the value of attribute default_headers.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def default_headers
  @default_headers
end

#password ⇒ Object (readonly)

Returns the value of attribute password.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def password
  @password
end

#query ⇒ Object (readonly)

Returns the value of attribute query.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def query
  @query
end

#uri ⇒ Object (readonly)

Returns the value of attribute uri.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def uri
  @uri
end

#uri_path ⇒ Object (readonly)

Returns the value of attribute uri_path.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def uri_path
  @uri_path
end

#uri_string ⇒ Object (readonly)

Returns the value of attribute uri_string.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def uri_string
  @uri_string
end

#username ⇒ Object (readonly)

Returns the value of attribute username.



27
28
29
 
# File 'lib/wrest/uri.rb', line 27

def username
  @username
end

Instance Method Details

#==(other) ⇒ Object 



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

def ==(other)
  return false if other.class != self.class

  other.uri == uri && username == other.username && 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



71
72
73
 
# File 'lib/wrest/uri.rb', line 71

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

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

:nodoc:



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

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:



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

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:



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

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:



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

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:



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

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

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

:nodoc:



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

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.



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

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) 


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

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 



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

def hash
  [@uri, @username, @password].hash
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.



100
101
102
 
# File 'lib/wrest/uri.rb', line 100

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.



51
52
53
54
 
# File 'lib/wrest/uri.rb', line 51

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