Class: Sawyer::Relation

Inherits:
Object
  • Object
show all
Defined in:
lib/sawyer/relation.rb

Defined Under Namespace

Classes: Map

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(agent, name, href, method = nil) ⇒ Relation

A Relation represents an available next action for a resource.

agent - The Sawyer::Agent that made the request. name - The Symbol name of the relation. href - The String URL of the location of the next action. method - The Symbol HTTP method. Default: :get



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/sawyer/relation.rb', line 108

def initialize(agent, name, href, method = nil)
  @agent = agent
  @name = name.to_sym
  @href = href
  @href_template = Addressable::Template.new(href.to_s)

  methods = nil

  if method.is_a? String
    if method.size.zero?
      method = nil
    else
      method.downcase!
      methods = method.split(',').map! do |m|
        m.strip!
        m.to_sym
      end
      method = methods.first
    end
  end

  @method = (method || :get).to_sym
  @available_methods = Set.new methods || [@method]
end

Instance Attribute Details

#agent ⇒ Object (readonly)

Returns the value of attribute agent.



56
57
58
 
# File 'lib/sawyer/relation.rb', line 56

def agent
  @agent
end

#available_methods ⇒ Object (readonly)

Returns the value of attribute available_methods.



56
57
58
 
# File 'lib/sawyer/relation.rb', line 56

def available_methods
  @available_methods
end

#href_template ⇒ Object (readonly)

Returns the value of attribute href_template.



56
57
58
 
# File 'lib/sawyer/relation.rb', line 56

def href_template
  @href_template
end

#method ⇒ Object (readonly)

Returns the value of attribute method.



56
57
58
 
# File 'lib/sawyer/relation.rb', line 56

def method
  @method
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



56
57
58
 
# File 'lib/sawyer/relation.rb', line 56

def name
  @name
end

Class Method Details

Public: Builds a single Relation from the given options. These are usually taken from a ‘_links` property in a resource.

agent - The Sawyer::Agent that made the request. name - The Symbol name of the Relation. options - A Hash containing the other Relation properties.

:href   - The String URL of the next action's location.
:method - The optional String HTTP method.

Returns a Relation.



93
94
95
96
97
98
99
100
 
# File 'lib/sawyer/relation.rb', line 93

def self.from_link(agent, name, options)
  case options
  when Hash
    new agent, name, options[:href], options[:method]
  when String
    new agent, name, options
  end
end

.from_links(agent, index, rels = Map.new) ⇒ Object

Public: Builds an index of Relations from the value of a ‘_links` property in a resource. :get is the default method. Any links with multiple specified methods will get multiple relations created.

index - The Hash mapping Relation names to the Hash Relation

options.

rels - A Relation::Map to store the Relations.

Returns a Relation::Map



71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/sawyer/relation.rb', line 71

def self.from_links(agent, index, rels = Map.new)
  if index.is_a?(Array)
    raise ArgumentError, "Links must be a hash of rel => {_href => '...'}: #{index.inspect}"
  end

  index.each do |name, options|
    rels << from_link(agent, name, options)
  end if index

  rels
end

Instance Method Details

#call(data = nil, options = nil) ⇒ Object

Public: Makes an API request with the curent Relation.

data - The Optional Hash or Resource body to be sent. :get or :head

requests can have no body, so this can be the options Hash
instead.

options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Raises ArgumentError if the :method value is not in @available_methods. Returns a Sawyer::Response.



259
260
261
262
263
264
265
266
 
# File 'lib/sawyer/relation.rb', line 259

def call(data = nil, options = nil)
  m = options && options[:method]
  if m && !@agent.allow_undefined_methods? && !@available_methods.include?(m == :head ? :get : m)
    raise ArgumentError, "method #{m.inspect} is not available: #{@available_methods.to_a.inspect}"
  end

  @agent.call m || @method, @href_template, data, options
end

#delete(data = nil, options = nil) ⇒ Object

Public: Makes an API request with the curent Relation using DELETE.

data - The Optional Hash or Resource body to be sent. options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



221
222
223
224
225
 
# File 'lib/sawyer/relation.rb', line 221

def delete(data = nil, options = nil)
  options ||= {}
  options[:method] = :delete
  call data, options
end

#get(options = nil) ⇒ Object

Public: Makes an API request with the curent Relation using GET.

data - The Optional Hash or Resource body to be sent. :get or :head

requests can have no body, so this can be the options Hash
instead.

options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



161
162
163
164
165
 
# File 'lib/sawyer/relation.rb', line 161

def get(options = nil)
  options ||= {}
  options[:method] = :get
  call options
end

#head(options = nil) ⇒ Object

Public: Makes an API request with the curent Relation using HEAD.

data - The Optional Hash or Resource body to be sent. :get or :head

requests can have no body, so this can be the options Hash
instead.

options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



144
145
146
147
148
 
# File 'lib/sawyer/relation.rb', line 144

def head(options = nil)
  options ||= {}
  options[:method] = :head
  call options
end

#href(options = nil) ⇒ Object 



242
243
244
245
 
# File 'lib/sawyer/relation.rb', line 242

def href(options = nil)
  return @href if @href_template.nil?
  @href_template.expand(options || {}).to_s
end

#inspect ⇒ Object 



268
269
270
 
# File 'lib/sawyer/relation.rb', line 268

def inspect
  %(#<#{self.class}: #{@name}: #{@method} #{@href_template}>)
end

#options(data = nil, opt = nil) ⇒ Object

Public: Makes an API request with the curent Relation using OPTIONS.

data - The Optional Hash or Resource body to be sent. options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



236
237
238
239
240
 
# File 'lib/sawyer/relation.rb', line 236

def options(data = nil, opt = nil)
  opt ||= {}
  opt[:method] = :options
  call data, opt
end

#patch(data = nil, options = nil) ⇒ Object

Public: Makes an API request with the curent Relation using PATCH.

data - The Optional Hash or Resource body to be sent. options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



206
207
208
209
210
 
# File 'lib/sawyer/relation.rb', line 206

def patch(data = nil, options = nil)
  options ||= {}
  options[:method] = :patch
  call data, options
end

#post(data = nil, options = nil) ⇒ Object

Public: Makes an API request with the curent Relation using POST.

data - The Optional Hash or Resource body to be sent. options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



176
177
178
179
180
 
# File 'lib/sawyer/relation.rb', line 176

def post(data = nil, options = nil)
  options ||= {}
  options[:method] = :post
  call data, options
end

#put(data = nil, options = nil) ⇒ Object

Public: Makes an API request with the curent Relation using PUT.

data - The Optional Hash or Resource body to be sent. options - Hash of option to configure the API request.

:headers - Hash of API headers to set.
:query   - Hash of URL query params to set.
:method  - Symbol HTTP method.

Returns a Sawyer::Response.



191
192
193
194
195
 
# File 'lib/sawyer/relation.rb', line 191

def put(data = nil, options = nil)
  options ||= {}
  options[:method] = :put
  call data, options
end