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

.serializerObject


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

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

Instance Attribute Details

#allow_undefined_methodsObject

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

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

#closeObject

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

#inspectObject


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

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

#marshal_dumpObject


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

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

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

#relsObject

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

#rootObject

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

#startObject

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_propertiesObject

private


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

def to_yaml_properties
  [:@endpoint]
end