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) 


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

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.



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/sawyer/agent.rb', line 85

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

#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).



124
125
126
 
# File 'lib/sawyer/agent.rb', line 124

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.



115
116
117
 
# File 'lib/sawyer/agent.rb', line 115

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

#expand_url(url, options = nil) ⇒ Object 



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

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 



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

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

#marshal_dump ⇒ Object 



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

def marshal_dump
  [@endpoint]
end

#marshal_load(dumped) ⇒ Object 



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

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

#parse_links(data) ⇒ Object 



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

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.



54
55
56
 
# File 'lib/sawyer/agent.rb', line 54

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

#root ⇒ Object

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

Returns a Sawyer::Response.



61
62
63
 
# File 'lib/sawyer/agent.rb', line 61

def root
  @root ||= start
end

#start ⇒ Object

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

Returns a Sawyer::Response.



68
69
70
 
# File 'lib/sawyer/agent.rb', line 68

def start
  call :get, @endpoint
end

#to_yaml_properties ⇒ Object

private



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

def to_yaml_properties
  [:@endpoint]
end