Class: Weary::Client

Inherits:
Object
  • Object
show all
Extended by:
Requestable
Includes:
Requestable
Defined in:
lib/weary/client.rb

Overview

An abstract class used to construct client libraries and the primary entrance point to use the Weary framework. Client defines a DSL to describe and construct a set of Resources, which in turn can generate Requests that can perform HTTP actions.

Resources are defined and stored by one of the class methods corresponding to an HTTP request method. Every Resource is declared with a name that acts as both a key to access the resource, and, when the class is instantiated, the name of a dynamically generated instance method.

Examples

class GiltSales < Weary::Client
  domain "https://api.gilt.com/v1"

  required :apikey

  optional :affid

  get :active, "/sales/active.json"

  get :active_in_store, "/sales/:store/active.json"

  get :upcoming, "/sales/upcoming.json"

  get :upcoming_in_store, "/sales/:store/upcoming.json"

  get :detail, "/sales/:store/:sale_key/detail.json"
end

sales = GiltSales.new
sales.active_in_store :store => :women, :apikey => "my-key"
# => A Weary::Request object

Constant Summary collapse

REQUEST_METHODS =

Internal: HTTP Request verbs supported by Weary. These translate to class methods of Client.

[
  :copy, :delete, :get, :head, :lock, :mkcol, :move, :options,
  :patch, :post, :propfind, :proppatch, :put, :trace, :unlock
]

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Requestable

adapter, has_middleware?, headers, pass_values_onto_requestable, use, user_agent

Constructor Details

#initialize {|_self| ... } ⇒ Client

Returns a new instance of Client.

Yields:

  • (_self)

Yield Parameters:

  • _self (Weary::Client) —

    the object that the method was called on



218
219
220
 
# File 'lib/weary/client.rb', line 218

def initialize
  yield self if block_given?
end

Class Method Details

.[](name) ⇒ Object

A quick getter to retrieve a Resource from the client’s internal store.

name - The Symbol name of the Resource.

Returns the Resource stored at name.



170
171
172
 
# File 'lib/weary/client.rb', line 170

def [](name)
  resources[name]
end

.[]=(name, resource) ⇒ Object

Store a Resource at the given key. A method is built for the instances with the same name as the key that calls the request method of the Resource.

name - A Symbol name of the Resource and the eventual name of the

method that will build the request.

resource - The Resource object to store. When the named method is

called on the client instance, this resource's request
method will be called.

Returns the stored Resource.



160
161
162
 
# File 'lib/weary/client.rb', line 160

def []=(name,resource)
  store name, resource
end

.call(env) ⇒ Object

A Rack middleware interface that uses the internal router to determine the best Resource available.

Returns an Array resembling a Rack response tuple.



185
186
187
 
# File 'lib/weary/client.rb', line 185

def call(env)
  route.call(env)
end

.defaults(hash = nil) ⇒ Object

An accessor to set default parameters to be used by the all of the resources described by the client.

hash - An optional Hash of key/value pairs describing the

default parameters to be sent to the resources

Returns a Hash of the default parameters sent to all resources.



115
116
117
118
 
# File 'lib/weary/client.rb', line 115

def defaults(hash=nil)
  @defaults = hash unless hash.nil?
  @defaults ||= {}
end

.domain(host = nil) ⇒ Object

An accessor to set the domain where the client’s resources are located. This is prepended to the resources’ path to form the resource uri.

host - An optional String to set the client domain.

Returns the domain String.



81
82
83
84
 
# File 'lib/weary/client.rb', line 81

def domain(host=nil)
  @domain = host unless host.nil?
  @domain ||= ""
end

.optional(*params) ⇒ Object

An accessor to set optional parameters permitted by all resources described by the client.

params - Zero or more Symbol parameters expected by the resources.

Returns an Array of parameters.



92
93
94
95
 
# File 'lib/weary/client.rb', line 92

def optional(*params)
  @optional = params unless params.empty?
  @optional ||= []
end

.required(*params) ⇒ Object

An accessor to set parameters required by the all of the resources of the client.

params - Zero or more Symbol parameters required by the resources.

Returns an Array of parameters.



103
104
105
106
 
# File 'lib/weary/client.rb', line 103

def required(*params)
  @required = params unless params.empty?
  @required ||= []
end

.resource(name, method, path = "") {|resource| ... } ⇒ Object

Internal: Create and build a resource description of a request. The resource is then stored in an internal hash, generating an instance method.

name - A Symbol name/descriptor of the resource. method - A Symbol or String of the request method used in the request. path - A String path to the resource that is appended to the domain

to form the uri.

Yields the Resource for further construction.

Returns the generated Resource.

Yields:



132
133
134
135
136
137
138
139
140
 
# File 'lib/weary/client.rb', line 132

def resource(name, method, path="")
  resource = Weary::Resource.new method, "#{domain}#{path}"
  resource.optional *optional
  resource.required *required
  resource.defaults defaults
  pass_values_onto_requestable resource
  yield resource if block_given?
  self[name] = resource
end

.resources ⇒ Object

A getter for the stored table of Resources.

Returns a Hash of Resources stored by their name keys.



145
146
147
 
# File 'lib/weary/client.rb', line 145

def resources
  @resources ||= {}
end

.route ⇒ Object

Internal: Build a Rack router for the client’s resources.

Returns a Route object of the resources at the domain.



177
178
179
 
# File 'lib/weary/client.rb', line 177

def route
  Weary::Route.new resources.values, domain
end