Class: Sawyer::Agent

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

Constant Summary collapse

NO_BODY = 
Set.new([:get, :head])

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(endpoint, options = nil) {|@conn| ... } ⇒ Agent

Agents handle making the requests, and passing responses to Sawyer::Response.

endpoint - String URI of the API entry point. options - Hash of options.

:allow_undefined_methods  - Allow relations to call all the HTTP verbs,
                            not just the ones defined.
:faraday                  - Optional Faraday::Connection to use.
:links_parser             - Optional parser to parse link relations
                            Defaults: Sawyer::LinkParsers::Hal.new
:serializer               - Optional serializer Class.  Defaults to
                            self.serializer_class.

Yields the Faraday::Connection if a block is given.

Yields:

  • (@conn) 


41
42
43
44
45
46
47
48
49
 
# File 'lib/sawyer/agent.rb', line 41

def initialize(endpoint, options = nil)
  @endpoint = endpoint
  @conn = (options && options[:faraday]) || Faraday.new
  @serializer = (options && options[:serializer]) || self.class.serializer
  @links_parser = (options && options[:links_parser]) || Sawyer::LinkParsers::Hal.new
  @allow_undefined_methods = (options && options[:allow_undefined_methods])
  @conn.url_prefix = @endpoint
  yield @conn if block_given?
end

Class Attribute Details

.serializer ⇒ Object 



15
16
17
 
# File 'lib/sawyer/agent.rb', line 15

def self.serializer
  @serializer ||= Serializer.any_json
end

Instance Attribute Details

#allow_undefined_methods ⇒ Object

Returns the value of attribute allow_undefined_methods.



9
10
11
 
# File 'lib/sawyer/agent.rb', line 9

def allow_undefined_methods
  @allow_undefined_methods
end

#links_parser ⇒ Object

Returns the value of attribute links_parser.



8
9
10
 
# File 'lib/sawyer/agent.rb', line 8

def links_parser
  @links_parser
end

Class Method Details

.decode(data) ⇒ Object 



23
24
25
 
# File 'lib/sawyer/agent.rb', line 23

def self.decode(data)
  serializer.decode(data)
end

.encode(data) ⇒ Object 



19
20
21
 
# File 'lib/sawyer/agent.rb', line 19

def self.encode(data)
  serializer.encode(data)
end

Instance Method Details

#allow_undefined_methods? ⇒ Boolean

Returns:

  • (Boolean) 


142
143
144
 
# File 'lib/sawyer/agent.rb', line 142

def allow_undefined_methods?
  !!@allow_undefined_methods
end

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

Makes a request through Faraday.

method - The Symbol name of an HTTP method. url - The String URL to access. This can be relative to the Agent’s

endpoint.

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.

Returns a Sawyer::Response.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/sawyer/agent.rb', line 90

def call(method, url, data = nil, options = nil)
  if NO_BODY.include?(method)
    options ||= data
    data      = nil
  end

  options ||= {}
  url = expand_url(url, options[:uri])
  started = nil
  res = @conn.send method, url do |req|
    if data
      req.body = data.is_a?(String) ? data : encode_body(data)
    end
    if params = options[:query]
      req.params.update params
    end
    if headers = options[:headers]
      req.headers.update headers
    end
    started = Time.now
  end

  Response.new self, res, :sawyer_started => started, :sawyer_ended => Time.now
end

#close ⇒ Object

Public: Close the underlying connection.



52
53
54
 
# File 'lib/sawyer/agent.rb', line 52

def close
  @conn.close if @conn.respond_to?(:close)
end

#decode_body(str) ⇒ Object

Decodes a String response body to a resource.

str - The String body from the response.

Returns an Object resource (Hash by default).



129
130
131
 
# File 'lib/sawyer/agent.rb', line 129

def decode_body(str)
  @serializer.decode(str)
end

#encode_body(data) ⇒ Object

Encodes an object to a string for the API request.

data - The Hash or Resource that is being sent.

Returns a String.



120
121
122
 
# File 'lib/sawyer/agent.rb', line 120

def encode_body(data)
  @serializer.encode(data)
end

#expand_url(url, options = nil) ⇒ Object 



137
138
139
140
 
# File 'lib/sawyer/agent.rb', line 137

def expand_url(url, options = nil)
  tpl = url.respond_to?(:expand) ? url : Addressable::Template.new(url.to_s)
  tpl.expand(options || {}).to_s
end

#inspect ⇒ Object 



146
147
148
 
# File 'lib/sawyer/agent.rb', line 146

def inspect
  %(<#{self.class} #{@endpoint}>)
end

#marshal_dump ⇒ Object 



155
156
157
 
# File 'lib/sawyer/agent.rb', line 155

def marshal_dump
  [@endpoint]
end

#marshal_load(dumped) ⇒ Object 



159
160
161
 
# File 'lib/sawyer/agent.rb', line 159

def marshal_load(dumped)
  @endpoint = *dumped.shift(1)
end

#parse_links(data) ⇒ Object 



133
134
135
 
# File 'lib/sawyer/agent.rb', line 133

def parse_links(data)
  @links_parser.parse(data)
end

#rels ⇒ Object

Public: Retains a reference to the root relations of the API.

Returns a Sawyer::Relation::Map.



59
60
61
 
# File 'lib/sawyer/agent.rb', line 59

def rels
  @rels ||= root.data._rels
end

#root ⇒ Object

Public: Retains a reference to the root response of the API.

Returns a Sawyer::Response.



66
67
68
 
# File 'lib/sawyer/agent.rb', line 66

def root
  @root ||= start
end

#start ⇒ Object

Public: Hits the root of the API to get the initial actions.

Returns a Sawyer::Response.



73
74
75
 
# File 'lib/sawyer/agent.rb', line 73

def start
  call :get, @endpoint
end

#to_yaml_properties ⇒ Object

private



151
152
153
 
# File 'lib/sawyer/agent.rb', line 151

def to_yaml_properties
  [:@endpoint]
end